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 accepts an idempotency key so a retried proposal is filed 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 |
| 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 |
| 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 |
| Unknown capability, or the requested item is not in this project | Check the capability name and the IDs you pass |
409 |
| The idempotency key was used with different input | Use a new idempotency key for a new proposal |
422 |
| Invalid body or input, or a project ID in the body | Fix the fields listed in |
429 |
| A rate limit was reached | Wait the number of seconds in the Retry-After response header |
500 |
| Internal error | Retry later. Contact support if it persists |
503 |
| We could not check your key or rate limit right now, the capability is not enabled for your project, or the key's creator already has 50 proposals waiting in this project | Retry later. For cockpit and sentiment capabilities, check that the feature is enabled. For proposals, confirm or cancel waiting ones on the Setup proposals page |
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
proposeCreatePersona and proposeCreateSchedule accept an idempotency key but don't require one. Send one, so that retrying after a timeout doesn't file a second proposal. Over HTTP, send it in the Idempotency-Key request header. Over MCP, pass it as the idempotencyKey argument.
Use a new key for each proposal, for example a UUID. A key stays tied to the proposal it filed.
Same key, same input: returns the same proposal with its current status and files nothing new. This also works after the proposal was confirmed, cancelled or expired, and when you already have 50 proposals waiting.
Same key, different input: 409
conflict.No key: every call files a new proposal.