Errors and retries

Error envelope

Every public API error includes error.code, error.message, error.request_id and error.details.resolution_url. Rely on code rather than message

Retry policy

• Do not retry expected 401, 403 or 422 errors without changing the request
• Retry 429 only after Retry-After or X-RateLimit-Reset with a small random delay
• Use bounded exponential backoff for network failures and temporary 5xx errors
• After an uncertain response to POST /uploads or POST /transcriptions, reuse the original Idempotency-Key