Skip to content
Docs menu

Errors, limits, idempotency and pagination

How the workspace APIs answer errors, how many requests they take a minute, how to retry a create without making it twice, how to write only when nothing changed since your read, and how to page through lists.

View .md

These rules hold for the MCP servers under /workspace/mcp and the REST twin under /api/v1, because a REST route runs the MCP tool. The product APIs of Flags, Forms, Incidents, Experiments and Comms follow the same error shape with a few differences, noted below. The inference and admin APIs have their own page: Venom Cloud APIs overview.

Errors

A REST error is JSON with a status code:

{ "error": { "message": "ENG-12 changed since you read it (now version …); nothing was written.", "type": "invalid_request_error", "code": "version_conflict", "param": null } }

Branch on the status and code; message is written for people and is the tool's own words.

Status code Means
400 invalid_request a parameter or field is missing or wrong, or the route does not take it (the message lists what it takes); If-Match or Idempotency-Key on a route whose tool has no such argument
401 invalid_api_key and others no credential, or one that is not valid; WWW-Authenticate points at the OAuth metadata
403 forbidden the credential may not do this: a read-only role, a team key on a personal product, a missing add-on, a scope the grant lacks, another agent's claim
404 not_found no such route, or no such thing that you can see
405 method_not_allowed the path exists with another method
412 version_conflict the thing changed since the If-Match version you sent; nothing was written
413 payload_too_large a body over 2 MiB
422 tool_error the tool refused in words, for example an edit anchor that is no longer in the note
429 rate_limit_exceeded over the rate window; Retry-After says how many seconds to wait
501 not_implemented the route's tool is not on this deployment yet

Over MCP the same refusals come back as a tool result with isError: true and the message as text, so an agent reads why and can fix its call. A malformed JSON-RPC request gets a JSON-RPC error instead.

The REST twin derives 404, 403 and 412 from the tool's words, and anything it cannot place is 422. The product APIs (Flags, Forms, Incidents, Experiments) answer a stale write with 409 version_conflict instead of 412.

Rate limits

API Limit Counted per
MCP and the REST twin (every Venom MCP server) 240 requests a minute agent: a personal key's agent, each connected app, each service agent, each name sent in x-venom-agent
MCP and the REST twin 960 requests a minute credential, over all its agents
Flags, Forms and Incidents APIs 600 requests a minute credential

A workspace_batch_run (or POST /api/v1/batch) counts one request more for each write step in it. Past a limit the answer is 429 with Retry-After, and the message says which limit. Windows start on the UTC minute. The inference API's limits are the key's own rpm and tpm (Venom Cloud APIs overview).

Retry a 429 after Retry-After, and a 502, 503 or 504 with backoff. Do not retry 400, 401, 403, 404 or 422 unchanged: they will fail the same way.

Retries without duplicates: Idempotency-Key

A create that takes an idempotency key runs once per key. Send a unique value (a UUID) as the Idempotency-Key header over REST, or as the idempotency_key argument over MCP.

  • A retry with the same key within 24 hours returns the first answer and creates nothing. Over MCP the answer ends with a "Replayed" line.
  • A call that was refused, or that crashed, frees its key, so you can fix the call and retry with the same key.
  • While the first call is still running, a retry is refused; wait and try again.
  • Reusing a key for a different tool is refused. Keys belong to your credential and your organisation.
  • A route whose tool takes no key answers 400 when you send the header.

12 tools take idempotency_key (generated from the tools' input schemas):

  • Calendar: calendar_booking_create
  • Comms: comms_call_place, comms_message_send
  • Notes: globe_database_create, globe_database_import, globe_note_write, globe_row_create, globe_suggestion_create
  • Tasks: tasks_comment_create, tasks_issue_create, tasks_issue_duplicate, tasks_issue_progress

The Flags, Forms, Experiments and Comms APIs take Idempotency-Key on their creates too, with the same 24 hours. The inference API's Idempotency-Key is different: it re-attaches to a running job.

Safe writes: ETag and If-Match

A read of a note, an issue or a database answers its version as the ETag header (and as version in the body). Send it back as If-Match on a write, or as expect_version over MCP. If the thing changed since your read, nothing is written: 412 over REST, a refusal over MCP. Read it again and redo your change.

16 tools take expect_version (generated from the tools' input schemas):

  • Notes: globe_database_delete, globe_database_update, globe_note_delete, globe_note_edit, globe_note_property_update, globe_note_write, globe_row_delete, globe_row_update, globe_version_restore, globe_view_create, globe_view_update
  • Studio: studio_artifact_update, studio_content_edit, studio_html_edit, studio_version_restore
  • Tasks: tasks_issue_update

Anchored edits (edits on globe_note_edit and tasks_issue_update) need no version most of the time: each anchor must still match exactly once, or nothing changes.

Pagination

Most lists page with a cursor, and new lists always do; each tool says which arguments it takes, and its REST route takes the same ones as query parameters.

  • Cursor. The answer carries a cursor (next_cursor, or a "Cursor:" or "More:" line in text). Pass it back as cursor to get the next page; next_cursor is null on the last page. A cursor a list did not give is refused in words. Every list tool pages this way, in every product except Computers (a list read in full gives 100 rows by default, at most 500; a long list such as messages or audit entries states its own default). A list that also takes before, after or offset still does, and cursor works on top of them. workspace_change_list works this way too, so keep its cursor to follow changes.
  • Offset. A few lists take offset and limit.
  • Before. Time-ordered lists such as a person's interactions or a check's results take before (the oldest item you have) and limit.
  • Since. since (an ISO time) returns only what changed after it, so a client that checks back re-reads nothing.
  • Limit. limit caps a page. Each tool states its default and maximum in its input schema.

226 tools take cursor (generated from the tools' input schemas):

  • Admin: admin_alert_hit_list, admin_alert_list, admin_audit_list, admin_autoscale_list, admin_bot_list, admin_budget_list, admin_daemon_list, admin_daemon_share_list, admin_eval_list, admin_experiment_list, admin_failure_list, admin_filter_list, admin_gear_list, admin_grant_list, admin_guardrail_list, admin_handoff_list, admin_integration_list, admin_key_list, admin_library_list, admin_live_list, admin_mcp_catalog_list, admin_mcpserver_list, admin_member_list, admin_memory_list, admin_myguardrail_list, admin_onboarding_list, admin_pack_list, admin_pause_list, admin_prompttest_list, admin_provider_list, admin_share_list, admin_skill_list, admin_spendalert_list, admin_spendlimit_list, admin_sso_group_list, admin_team_list, admin_webhook_delivery_list, admin_webhook_list
  • Agents: agents_attachment_list, agents_bot_list, agents_bot_routine_list, agents_bot_run_event_list, agents_bot_run_list, agents_bot_summary_list, agents_chat_list, agents_gear_list, agents_project_list, agents_server_list, agents_skill_list, agents_workspace_list
  • Calendar: calendar_account_list, calendar_booking_list, calendar_calendar_list, calendar_event_type_list, calendar_feed_list, calendar_offer_list, calendar_poll_list, calendar_reminder_list, calendar_schedule_list
  • Chat: chat_bookmark_list, chat_change_list, chat_channel_list, chat_feed_list, chat_keyword_list, chat_member_list, chat_message_list, chat_unread_list
  • Comms: comms_call_list, comms_conversation_list, comms_message_list, comms_optout_list, comms_profile_list, comms_provider_list, comms_sender_list, comms_template_list
  • Computers: computers_approval_list, computers_daemon_list, computers_routine_list, computers_routine_run_list, computers_run_list, computers_tab_list
  • Experiments: exp_event_list, exp_experiment_list, exp_insight_list, exp_metric_list
  • Flags: flags_approval_list, flags_change_list, flags_coderef_list, flags_environment_list, flags_flag_history, flags_flag_list, flags_project_list, flags_segment_list, flags_webhook_list
  • Forms: forms_delivery_list, forms_feed_list, forms_form_list, forms_response_list
  • Funnel: funnel_deal_list, funnel_field_list, funnel_goal_list, funnel_outreach_enrollment_list, funnel_outreach_queue_list, funnel_outreach_sequence_list, funnel_pipeline_list, funnel_product_list
  • Notes: globe_automation_list, globe_comment_list, globe_dashboard_list, globe_database_list, globe_favorite_list, globe_import_job_list, globe_import_list, globe_note_list, globe_notification_list, globe_row_list, globe_share_list, globe_shared_list, globe_source_list, globe_suggestion_list, globe_synced_list, globe_team_list, globe_team_member_list, globe_template_list, globe_trash_list, globe_vault_list, globe_version_list
  • Incidents: incidents_alert_hit_list, incidents_alert_list, incidents_artifact_list, incidents_error_list, incidents_event_list, incidents_incident_list, incidents_oncall_member_list, incidents_oncall_policy_list, incidents_oncall_schedule_list, incidents_oncall_source_list, incidents_project_list, incidents_release_list, incidents_rule_list
  • Org: org_team_list
  • People: people_attachment_list, people_brief_list, people_circle_list, people_classifier_history, people_company_list, people_controversy_list, people_correction_list, people_downvote_list, people_event_list, people_followup_list, people_graph_get, people_image_list, people_interaction_list, people_intro_list, people_introask_list, people_link_list, people_meeting_list, people_meetingreview_list, people_outreach_list, people_overnight_list, people_proposal_list, people_relationship_list, people_suggestion_list, people_trip_list
  • Status page: status_check_list, status_component_list, status_maintenance_list, status_subscriber_list
  • Studio: studio_artifact_list, studio_share_list, studio_theme_list, studio_version_list
  • Support: support_conversation_list, support_help_article_list, support_macro_list, support_message_list, support_sla_policy_list
  • Tasks: tasks_activity_list, tasks_agent_list, tasks_attachment_list, tasks_comment_list, tasks_cycle_list, tasks_dependency_list, tasks_document_list, tasks_export_list, tasks_favorite_list, tasks_follow_list, tasks_import_job_list, tasks_initiative_list, tasks_initiative_update_list, tasks_issue_search, tasks_label_list, tasks_labelgroup_list, tasks_link_list, tasks_member_list, tasks_milestone_list, tasks_note_list, tasks_notification_list, tasks_project_list, tasks_projectdep_list, tasks_projectlink_list, tasks_projectrequest_list, tasks_projectupdate_list, tasks_pullrequest_list, tasks_pulse_digest_list, tasks_recurring_list, tasks_release_list, tasks_releasekey_list, tasks_releasepipeline_list, tasks_reminder_list, tasks_request_list, tasks_saved_insight_list, tasks_state_list, tasks_suggestion_list, tasks_team_list, tasks_teammember_list, tasks_template_list, tasks_triagerule_list, tasks_updatecomment_list, tasks_view_list
  • Cross-product: workspace_agent_list, workspace_change_list, workspace_draft_list, workspace_link_list, workspace_product_list

7 tools take offset (generated from the tools' input schemas):

  • Funnel: funnel_deal_list
  • Notes: globe_note_get, globe_row_list
  • People: people_person_search, people_reach_search
  • Support: support_conversation_list
  • Tasks: tasks_issue_get

12 tools take before (generated from the tools' input schemas):

  • Admin: admin_alert_hit_list, admin_audit_list, admin_webhook_delivery_list
  • Chat: chat_message_list
  • Computers: computers_activity_list
  • Forms: forms_delivery_list, forms_form_history
  • Funnel: funnel_deal_move
  • People: people_interaction_list
  • Status page: status_check_results
  • Tasks: tasks_pulse_get, tasks_releasechangelog_get

10 tools take since (generated from the tools' input schemas):

  • Admin: admin_audit_list
  • Chat: chat_message_search
  • Flags: flags_flag_history
  • Notes: globe_note_list
  • Incidents: incidents_incident_get
  • People: people_relationship_create
  • Tasks: tasks_flow_insight_get, tasks_insight_get, tasks_issue_search
  • Cross-product: workspace_change_list

JSON answers and fields

Over REST, a tool that has a JSON form always answers JSON (the route sets format: "json" for you). Other answers are { "text": "…", "id": "…" }: the tool's words and, for a create, the id it made. Over MCP, pass format: "json" to get structuredContent; the default is short markdown, which is cheaper in an agent's context. fields picks what each row of a list carries.

6 tools take fields (generated from the tools' input schemas):

  • Forms: forms_response_list
  • Notes: globe_note_list
  • Studio: studio_artifact_get
  • Tasks: tasks_issue_list_mine, tasks_issue_search, tasks_template_apply

Sizes

  • A request body is at most 2 MiB (413 past it).
  • workspace_batch_run runs 1 to 25 steps.
  • workspace_item_search waits up to 3 seconds for each product and answers with what it has.