Errors, retries, and rate limits

All API errors use one stable envelope:

{
  "error": {
    "type": "validation_error",
    "code": "unknown_inputs",
    "message": "One or more inputs are not declared by this capability",
    "param": "inputs",
    "details": {"unknown": ["foo"]},
    "request_id": "..."
  }
}

Every response includes a request ID. Keep it when contacting support.

The SDK maps responses to ApiError, AuthenticationError, ValidationError, RateLimitError, and InsufficientCreditsError. A terminal unsuccessful job raises RunFailed; a caller timeout raises RunTimeout with the active run handle.

Idempotency

POST /runs requires Idempotency-Key. The SDK generates one by default, or accepts idempotency_key=. Repeating the same key and canonical request returns the original run. Reusing a key with different content returns 409 idempotency_conflict.

Transport retries

The SDK automatically retries transient transport failures and HTTP 408, 425, 429, 500, 502, 503, and 504 responses with bounded exponential backoff and jitter. It respects Retry-After when present.

Rate limits

Limits are enforced per API key. Run creation has a stricter bucket than general reads, and account-level compute concurrency is enforced separately. Inspect:

RateLimit-Limit
RateLimit-Remaining
RateLimit-Reset
Retry-After

Do not retry validation, authentication, or idempotency-conflict responses without changing the request.