Errors

Every error has the same shape, a stable code, and a message you can show people.

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

StatusCodeWhat it meansWhat to do
400bad_requestThe request can't be done, like an unknown column or a group from another project.Read the message; fix the request.
401missing_keyThere's no Authorization: Bearer header.Send the key.
401invalid_keyThe key is wrong, revoked or expired, or its owner left.Make a new key.
402insufficient_creditsAn AI-powered call needs credits the organization doesn't have.Ask an admin to add credits.
402budget_reachedThe organization's monthly AI budget is used up.An admin can raise it under Billing.
402member_limit_reachedThe key's owner reached their own monthly AI credit limit.Wait for next month, or ask an admin.
403missing_scopeThe key doesn't have the scope this needs.Use a key with that scope.
403api_disabledAn admin turned the API off for the organization.Ask an admin.
403forbiddenThe key's owner isn't allowed to do this, like a viewer making a change.Use a key from someone who can.
404not_foundIt doesn't exist, or the key's owner can't see it.Check the id and the owner's access.
409idempotency_key_reusedThat Idempotency-Key was used for a different request.Use a new key for each change. See idempotency.
409conflictThe change clashes with the current state.Read the item again, then retry.
422invalid_requestA parameter is missing or out of range.The message names each one.
429rate_limitedToo many requests from this key this minute.Wait Retry-After seconds.
429daily_limitThe organization reached its daily limit.Wait until midnight UTC.
500internal_errorSomething 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()