Skip to main content

Errors

API errors are 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.

StatusCodeWhat to do
400invalid_requestFix the input; issues names each field that is wrong.
401identity.unauthenticatedThe key is missing, unknown, expired or revoked: use a valid one.
403identity.missing_permissionGive the key the permission in details.permission, or use another.
403identity.api_key_not_allowedThis operation is not part of the public API.
404not_found and othersIt does not exist in your account.
409per operationThe state does not allow it yet, such as completing an empty upload.
429identity.too_many_requestsSee rate limits.
5xxinternal_error and othersRetry later with backoff.

Retries​

Retry a 429 after Retry-After. For reads, retry 5xx responses and network failures with exponential backoff and a bounded number of attempts. Do not retry a write blindly: its effect may have happened before the answer was lost.

Creating an upload is not idempotent. Repeating its POST creates another asset, and completing an upload twice returns a conflict. Follow Upload media for recovery at each step.

The PUT to the signed upload URL goes directly to storage. Its errors may be XML, and a 412 can mean the file was already written. It does not use the API's JSON error format.