Errors

Every error is JSON with a stable code, a message you may show, and sometimes details:

{
  "code": "identity.missing_permission",
  "error": "This API key needs the permission runs:read.",
  "details": { "permission": "runs:read" }
}

Match on code, never on the message.

Status	Code	What to do
400	invalid_request	Fix the input; issues names each field that is wrong.
401	identity.unauthenticated	The key is missing, unknown, expired or revoked: use a valid one.
403	identity.missing_permission	Give the key the permission in details.permission, or use another.
403	identity.api_key_not_allowed	This operation is not part of the public API.
404	not_found and others	It does not exist in your account.
409	per operation	The state does not allow it yet, such as completing an empty upload.
429	identity.too_many_requests	See rate limits.
5xx	internal_error and others	Retry later with backoff.

Retries

Retry a 429 after Retry-After, and a 5xx or a network failure with exponential backoff. Reads are always safe to retry. For uploads, see Upload media.