# Errors, retries, and rate limits All API errors use one stable envelope: ```json { "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: ```text RateLimit-Limit RateLimit-Remaining RateLimit-Reset Retry-After ``` Do not retry validation, authentication, or idempotency-conflict responses without changing the request.