API error reference

Every failure the API can return. Branch on error.code, never on the message: the codes are stable, the wording is not.

{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "This API key is missing the required scope: videos:write.",
    "details": { "required_scopes": ["videos:write"], "granted_scopes": ["videos:read"] },
    "hint": "...what to do about it",
    "retryable": false,
    "request_id": "req_8f3c...",
    "doc_url": "https://autostud.ai/docs/api/errors#insufficient_scope"
  }
}

retryable says whether repeating the identical request can ever succeed. When it is false, change something before calling again.

400 invalid_request_error

invalid_requestnot retryable

Re-read the endpoint contract before retrying: GET /api/v1/openapi.json, or `describe` over MCP.

invalid_jsonnot retryable

The body was not valid JSON. Send a JSON object with Content-Type: application/json.

test_mode_unsupportednot retryable

This action cannot be simulated. Repeat it with a live `sk_live_` key -- it will spend credits.

401 authentication_error

missing_credentialsnot retryable

Send `Authorization: Bearer sk_live_...` or an `X-Api-Key` header. Keys are minted at /app/settings/api-keys.

invalid_credentialsnot retryable

That key is not recognised. Mint a new one at /app/settings/api-keys -- keys are shown once and cannot be re-read.

key_revokednot retryable

This key was revoked. Mint a replacement at /app/settings/api-keys.

key_expirednot retryable

This key passed its expiry date. Mint a new one at /app/settings/api-keys.

402 billing_error

insufficient_creditsnot retryable

`details` carries the shortfall. Top up at /app/pricing, or run the same call with an `sk_test_` key to validate it for free.

403 permission_error

key_pausednot retryable

This key is paused. Re-enable it at /app/settings/api-keys, or use another one.

ip_not_allowednot retryable

This key restricts calling IPs. Add the address to its allow-list at /app/settings/api-keys.

origin_not_allowednot retryable

This key restricts browser origins. Add the origin at /app/settings/api-keys, or call from a server.

insufficient_scopenot retryable

`details.required_scopes` lists what is missing. Call GET /api/v1 to see what this key does hold, then re-scope it at /app/settings/api-keys.

workspace_mismatchnot retryable

That record belongs to another workspace. Pass the right `X-Workspace-Id`, or list the resource first to get an id you can reach.

404 not_found_error

not_foundnot retryable

No record with that id in this workspace. List the resource to get a valid id -- do not construct one.

405 invalid_request_error

method_not_allowednot retryable

Wrong verb for this path. GET /api/v1 lists each resource with the operations it supports.

406 invalid_request_error

unsupported_formatnot retryable

Supported formats are json, ndjson and csv, chosen with `?format=`.

409 conflict_error

conflictretryable

The record changed underneath this request. Re-fetch it and reapply the change.

idempotency_conflictnot retryable

This Idempotency-Key was already used with a different body. Use a new key, or resend the original body.

idempotency_in_progressretryable

The first request with this Idempotency-Key is still running. Wait and retry with the same key -- do not start a second one.

413 invalid_request_error

payload_too_largenot retryable

Split the payload: /v1/batch takes 20 sub-requests, /v1/{resource}/bulk takes 100 items.

422 validation_error

validation_failednot retryable

`details.issues` names each offending field. Fix them and retry; retrying unchanged will fail identically.

429 rate_limit_error

rate_limit_exceededretryable

Wait for `Retry-After` seconds, then retry. Back off rather than looping; the window is per key.

quota_exceedednot retryable

The monthly request quota for this key is spent. GET /api/v1/usage shows the period, and the plan can be raised at /app/pricing.

500 api_error

internal_errorretryable

Our side failed, not the request. Retry with backoff and quote `request_id` if it persists.

502 api_error

upstream_errorretryable

A provider we depend on failed. This one is worth retrying with backoff; it is not caused by the request.

See also the API reference, the OpenAPI spec and /llms-full.txt.