Errors and retries

Error response format

An error always arrives in this envelope.

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Request limit exceeded",
    "retryable": true,
    "request_id": "0b7b8f0e-0000-4000-8000-000000000010",
    "details": {"reset_at": "2026-10-05T09:01:00+00:00"}
  }
}

• Every response has an X-Request-Id header equal to request_id in the body. The server issues a new one for each request.
• 429 and some 503 responses have a Retry-After header (seconds).
• Every response is Cache-Control: no-store.
• You can send X-Correlation-Id for tracing on your side. It is separate from the server generated request_id.
• A Turn or Run that was accepted (202) and fails later is not an HTTP error. You read it from error.code in the detail response.

Retry principles

1. Retry only errors whose retryable is true and network errors (dropped connection, timeout).
2. If Retry-After is present, wait that long. Otherwise use exponential backoff plus random jitter.
3. When you retry a create, input, cancel, or upload request, send the same Idempotency-Key and the same body. If the request was already accepted, the same receipt comes back, so nothing runs twice.
4. An error with retryable of false gives the same result if you resend it unchanged. Fix the request or the cause.
5. If you resend a request whose response you never received under a new key, the same work can run twice. Do not change the key when retrying.
6. Put a cap on the number of retries and the total wait.

def post_with_retry(url: str, key: str, body: dict, attempts: int = 5) -> httpx.Response:
    for attempt in range(attempts):
        try:
            response = httpx.post(url, headers={**AUTH, "Idempotency-Key": key}, json=body, timeout=30)
        except httpx.TransportError:
            response = None
        if response is not None and response.status_code < 400:
            return response
        try:
            error = response.json().get("error", {}) if response is not None else {}
        except ValueError:  # a proxy may answer 502/503/504 without the JSON envelope
            error = {"retryable": response.status_code in (429, 502, 503, 504)}
        if response is not None and not error.get("retryable"):
            response.raise_for_status()
        delay = float(response.headers.get("Retry-After", 0)) if response is not None else 0
        time.sleep(delay or min(30, 0.5 * 2 ** attempt))
    raise RuntimeError("gave up after retries")

What each HTTP status means

Error code table

This table lists the public codes a caller can receive. A code with HTTP status - appears not as an HTTP response but only in error.code of a Turn or Run detail, and its retryable is false there. retryable describes resending the same request, so it is always false on a finished execution. Whether to create a new execution follows the “What to do after a failed execution” table below. A code used both as an HTTP response and in execution details, such as SESSION_SANDBOX_UNAVAILABLE, has one row: the status and retryable columns describe the HTTP response, and the meaning column also explains what it means in execution details. Codes used only internally are not listed. New codes may be added, so handle an unknown code by retryable and the HTTP status.

What to do after a failed execution

Once a Turn or Run ends as FAILED, CANCELED, or EXPIRED, that execution does not come back. To try again, create a new Turn or Run with a new Idempotency-Key. This differs from the retry above, which resends an unanswered request with the same key. Reusing the finished execution’s key returns that finished execution’s receipt again.

Follow the order below even when an AI tool makes the calls for you. A new execution costs money again.

For a code not in this table, do not run again. Stop and tell a person.

When a result the AI employee produces during an execution breaks a public result rule, the execution ends as a failure right there. Among result format errors, only a schema mismatch in a JSON result is handed back to the AI employee during the execution to fix. In a workflow that returns only some results instead of failing (PARTIALLY_SUCCEEDED), the same code stays in error.code of the failed result item.

A failed organization work preparation is not an HTTP error either. Its reason is in the preparation’s reason_codes, and what to do next is in organization works.