When something goes wrong, the API answers with an HTTP status and this shape:
{
"error": {
"code": "missing_scope",
"message": "This key can't do that. It needs the projects:write scope."
}
}
Branch on code, which never changes. The message is written for people, so you can show it as is, but it may be reworded.
What to do about each
| Status | Code | What it means | What to do |
|---|---|---|---|
| 400 | bad_request | The request can't be done, like an unknown column or a group from another project. | Read the message; fix the request. |
| 401 | missing_key | There's no Authorization: Bearer header. | Send the key. |
| 401 | invalid_key | The key is wrong, revoked or expired, or its owner left. | Make a new key. |
| 402 | insufficient_credits | An AI-powered call needs credits the organization doesn't have. | Ask an admin to add credits. |
| 402 | budget_reached | The organization's monthly AI budget is used up. | An admin can raise it under Billing. |
| 402 | member_limit_reached | The key's owner reached their own monthly AI credit limit. | Wait for next month, or ask an admin. |
| 403 | missing_scope | The key doesn't have the scope this needs. | Use a key with that scope. |
| 403 | api_disabled | An admin turned the API off for the organization. | Ask an admin. |
| 403 | forbidden | The key's owner isn't allowed to do this, like a viewer making a change. | Use a key from someone who can. |
| 404 | not_found | It doesn't exist, or the key's owner can't see it. | Check the id and the owner's access. |
| 409 | idempotency_key_reused | That Idempotency-Key was used for a different request. | Use a new key for each change. See idempotency. |
| 409 | conflict | The change clashes with the current state. | Read the item again, then retry. |
| 422 | invalid_request | A parameter is missing or out of range. | The message names each one. |
| 429 | rate_limited | Too many requests from this key this minute. | Wait Retry-After seconds. |
| 429 | daily_limit | The organization reached its daily limit. | Wait until midnight UTC. |
| 500 | internal_error | Something broke on our side. | Retry with backoff; contact support if it continues. |
A 404 doesn't say whether something exists, so a key can't be used to discover things its owner can't see.
Over MCP
A failed tool call comes back with isError: true and the message as its text, so the agent can read it and adjust:
{
"isError": true,
"content": [{ "type": "text", "text": "This key can't do that. It needs the projects:write scope." }]
}
Handling errors in code
res = api.post(f"/projects/{project_id}/items", json={"title": "Call the venue"})
if res.is_error:
error = res.json()["error"]
if error["code"] == "missing_scope":
raise SystemExit("This key is read-only. Make a Full access key.")
raise RuntimeError(f"{res.status_code} {error['code']}: {error['message']}")
item = res.json()