Errors, rate limits and idempotency

The API returns a fixed error code for each kind of failure, limits each key to 60 requests per minute, and uses an idempotency key so a retried change is applied only once.

Errors

Every error from the HTTP API has the same body:

{
  "error": {
    "code": "invalid_input",
    "message": "The input is invalid.",
    "issues": [{ "path": ["limit"], "code": "invalid_type" }]
  }
}

The issues list appears only with status 422. It lists the field paths and error codes, never the values you sent. Error messages are fixed texts and never contain internal details.

Status	Code	Meaning	What to do
401	`unauthorized`	The key is missing, mistyped, revoked or expired, or its creator lost access to the project	Check that the key is sent as a bearer token in the authorization header, or create a new key
403	`forbidden`	The key's scopes or its creator's role do not allow this capability, or the project's plan does not include it	Use a key with the right scope, created by someone who can do this in the project
404	`not_found`	Unknown capability, or the requested item is not in this project	Check the capability name and the IDs you pass
409	`conflict`	The idempotency key was used with different input, or the first request with it is still running	Use a new idempotency key for a new change, or retry later
422	`invalid_input`	Invalid body or input, a project ID in the body, or a missing idempotency key	Fix the fields listed in `issues`
429	`rate_limited`	A rate limit was reached	Wait the number of seconds in the Retry-After response header
500	`internal`	Internal error	Retry later. Contact support if it persists
503	`unavailable`	We could not check your key or rate limit right now, or the capability is not enabled for your project	Retry later. For cockpit and sentiment capabilities, check that the feature is enabled

Over MCP, errors come back as tool errors with the text code: message, for example forbidden: You do not have permission to perform this action.

Rate limits

We count every authenticated request, including listing capabilities, fetching the OpenAPI document, and each MCP request.

Per key: 60 requests per minute.
Per organization: a daily limit that depends on your plan. API and MCP requests have their own daily counter, separate from Copilot.

Plan	Requests per organization per day
Trial	200
Starter	500
Growth	2,000
Enterprise	10,000

When you reach a limit, the response has status 429 and a Retry-After header in seconds. If we cannot check the limit, the response has status 503. Requests are never let through unchecked.

Idempotency

updateContentActionStatus changes data, so every call needs an idempotency key. Over HTTP, send it in the Idempotency-Key request header. Over MCP, pass it as the idempotencyKey argument. A retry with the same key never applies the change twice.

Use a new key for each change, for example a UUID. A key is valid for 24 hours in your project.
Same key, same input: returns the first response again and changes nothing.
Same key, different input: 409 conflict.
Same key while the first request is still running: 409 conflict. If that request crashed or timed out, the key is released after 5 minutes, and a retry with the same input runs once.
Failed call, for example 404 for an unknown action: the key is released and you can retry with it.
Missing key: 422 invalid_input.

Was this helpful?