Errors

Additional controls return 402 workspace_budget_exceeded and 403 model_not_allowed. A key concurrency refusal uses 429 rate_limit_exceeded with metadata.reason: key_concurrency and no timed retry header. See Rate limits & caps.

Shape

{
  "error": {
    "code": 429,
    "type": "rate_limit_exceeded",
    "message": "…"
  }
}

For Chat Completions, code is the HTTP status repeated in the body, so an SDK that surfaces only the body can still branch. Some errors add metadata — a 402 carries spend_usd and cap_usd, and a saturated 503 carries retry_after_s. The set of type values is open: treat an unknown value as a generic failure of the HTTP status. Every error response carries the X-Generation-Id header; quote it when you contact support.

The Responses route uses string error codes; Messages uses an Anthropic error envelope. Use the reference for the protocol you call.

Protocol and job failures

Upstream failures are normalized into the route's error shape. The set of types and reasons is open; for an unfamiliar value, keep the status, protocol, safe error fields and request or job IDs for support. Do not log keys, signed URLs or private input.

An accepted video with status: pending and queued: true is waiting to start. Poll its existing job ID instead of resubmitting. If its ten-minute wait expires before dispatch, status: failed with queue_expired: true and error.code: upstream_timeout reports an uncharged queue expiry; usage cost is zero and the reservation is released. This is distinct from an HTTP submission refusal or an expired download. See Video generation for cancellation and polling.

Reason metadata

metadata.reason refines a failure where present; it is not a universal retry flag. Key admission uses key_rpm, key_tpm and key_concurrency. no_provider_matches requires routing changes. idempotency_mismatch means the saved key/body pair differs; in_doubt means reconcile existing work. content_not_ready requires checking the job; content_expired means the output is no longer retrievable from that route. Character errors such as character_not_ready require checking the character before creating a video. See the operation schemas and guides for each family's reasons.

Media failure details

Supported media failures may add safe charged, alternatives and failed_provider fields in error.metadata. The charge value is true, false or unknown. Terminal video errors may carry the same safe metadata. Activity exposes only derived media_rerun details, never the original request body or arbitrary error metadata. See media offers and manually confirmed reruns.

Retrying safely and idempotency

• Fix 400, 401, 402 and 403 causes before retrying.
• A 503 whose metadata.reason is no_provider_matches needs different routing preferences. Repeating it unchanged cannot help.
• For supported asynchronous submits, keep the same Idempotency-Key and body. Poll the existing job to reconcile an uncertain submission; do not invent a new key to retry it.
• Retry read-only status lookups with bounded backoff for transient 429/5xx errors. Honour Retry-After when present. This does not authorize resubmitting generation.

import random, time
import requests

def get_job(url, api_key):
    # Reads an existing authenticated AI Hub job URL, never submits new work.
    for attempt in range(5):
        response = requests.get(url, headers={"Authorization": f"Bearer {api_key}"}, timeout=30)
        if response.status_code not in {429, 500, 502, 503} or attempt == 4:
            response.raise_for_status()
            return response.json()
        delay = response.headers.get("Retry-After", "")
        time.sleep(float(delay) if delay.isdigit() else min(2 ** attempt + random.random(), 30))