Docs · errors
Error handling for production integrations.
Handle authentication, validation, credits, rate limits, and provider failures explicitly. Retry transient failures with exponential backoff; do not retry malformed requests.
Status codes
| Status | Cause | Client behavior |
|---|---|---|
400 | validation errors: malformed JSON, missing content, unsupported context, or invalid URL. | Fix payload; do not retry unchanged. |
401 | invalid or missing API key. | Prompt for a fresh key; do not retry blindly. |
402 | insufficient credits. | Show balance/top-up flow or reduce the run. |
413 | content too large. | Chunk text or shrink media before retrying. |
415 | unsupported media type. | Submit a supported HTTPS image URL. |
429 | rate limited. | Respect Retry-After; create a free API key if the public demo limit is reached. |
5xx | transient Worker, provider, network, or model failure. | Retry with exponential backoff, max 3 attempts. |
Timeout guidance
- Text: use a 30s client timeout.
- Image: use a 60s client timeout.
- For batches, keep each item within documented caps and treat partial failures as retryable per item.
Retry policy
Use exponential backoff with jitter: 1s, 2s, 4s; max 3 attempts. Do not retry 400, 401, 402, 413, or 415 without changing the request or account state.
Billing guarantee: if analysis fails before returning a recommendation, it is not charged.
Example 429 body
{"error":"rate_limited","message":"Public demo limit reached. Create a free API key to keep testing with your own content."}