---
title: Errors, limits, idempotency and pagination
description: 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.
section: developers
order: 4
audience: [builder, agent]
sources: [services/nodejs-cloud/lib/mcp/rest.ts, services/nodejs-cloud/lib/mcp/limits.ts, services/nodejs-cloud/lib/mcp/idempotency.ts, services/nodejs-cloud/lib/mcp/workspace.ts, services/nodejs-cloud/lib/http/errors.ts, services/nodejs-cloud/lib/flags/auth.ts, services/nodejs-cloud/lib/forms/auth.ts, services/nodejs-cloud/lib/errors/auth.ts]
features: []
---

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](/docs/cloud/api-overview.md#errors).

## Errors {#errors}

A REST error is JSON with a status code:

```json
{ "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 {#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](/docs/cloud/api-overview.md#limits)).

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` {#idempotency}

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` {#versions}

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 {#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 {#json}

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 {#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.

## Related {#related}

- [Authentication and scopes](/docs/developers/auth.md)
- [The REST twin and OpenAPI](/docs/developers/rest.md)
- [Venom for agents](/docs/cloud/workspace-mcp.md#safe-writes-and-small-reads): the same rules as the MCP server describes them.
