# Error Handling

All errors are JSON and include a stable error `code` plus `request_id`.

## Error shape

```json
{
  "error": "Insufficient quota",
  "code": "quota_exceeded",
  "request_id": "req_123"
}
```

## Common codes

- `invalid_request`: request body, file, or parameter validation failed
- `unauthorized`: API key missing, invalid, or revoked
- `quota_exceeded`: account has insufficient credits/quota
- `rate_limited`: request frequency or concurrency limit exceeded
- `not_found`: job/document does not exist or is not accessible
- `internal_error`: unexpected server-side failure

## Recommended retry strategy

- Retry `429` and transient `5xx` with exponential backoff and jitter.
- Do not retry `400` until request payload is fixed.
- Do not retry `401` until key/config is fixed.
- For `402 quota_exceeded`, stop processing and trigger billing flow.

## Example retry backoff

- Attempt 1: wait 1s
- Attempt 2: wait 2s
- Attempt 3: wait 4s
- Attempt 4: wait 8s
- Add random jitter (+/- up to 20%)

## Support workflow

Persist `request_id` in your logs so support can trace issues quickly.