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.
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
400when 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 ascursorto get the next page;next_cursoris 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 takesbefore,afteroroffsetstill does, andcursorworks on top of them.workspace_change_listworks this way too, so keep its cursor to follow changes. - Offset. A few lists take
offsetandlimit. - Before. Time-ordered lists such as a person's interactions or a check's results take
before(the oldest item you have) andlimit. - Since.
since(an ISO time) returns only what changed after it, so a client that checks back re-reads nothing. - Limit.
limitcaps 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 (
413past it). workspace_batch_runruns 1 to 25 steps.workspace_item_searchwaits up to 3 seconds for each product and answers with what it has.
Related
- Authentication and scopes
- The REST twin and OpenAPI
- Venom for agents: the same rules as the MCP server describes them.