Know Exactly What Went Wrong

The Error Envelope

Every error returns the same JSON shape. The type groups the failure; the code is the stable, machine-readable discriminator you branch on; the message is human-readable and may change, so never parse it.

{
  "error": {
    "type": "validation_error",
    "code": "missing_field",
    "message": "workspace_id is required",
    "field": "workspace_id",
    "correlation_id": "req_01HX...",
    "retryable": false
  }
}

The correlation_id traces the full call in your dashboard. Quote it when you contact support, and log it so any failure is reproducible. retryable tells you whether trying again can help.

HTTP Status Codes

Retry Semantics

Retry only what is safe to retry. Reads are idempotent and always safe. For writes through the skills API, send an Idempotency-Key header. A retried call carrying the same key within 60 seconds replays the original response instead of running again, so a network retry cannot post twice. A response built from a replay carries X-Idempotent-Replayed: true.

• Retry on 429 and 5xx. Back off exponentially with jitter, capped at a handful of attempts.
• Do not retry on 400, 401, 403, 404, or 422. The same request fails the same way. Fix it first.
• On 429, read Retry-After (seconds) and wait at least that long. The rate-limit headers tell you when the window resets.

import time, random

def call_with_retry(fn, attempts=4):
    for i in range(attempts):
        resp = fn()
        if resp.status_code < 400:
            return resp
        if resp.status_code == 429:
            wait = float(resp.headers.get("Retry-After", 2 ** i))
            time.sleep(wait)
            continue
        if resp.status_code >= 500:
            time.sleep((2 ** i) + random.random())
            continue
        # 4xx other than 429: fix the request, don't retry
        resp.raise_for_status()
    resp.raise_for_status()

Code Dictionary