Error format
Analyze errors use application/problem+json, with an HTTP status and a machine-readable code:
{
"status": 402,
"title": "Payment Required",
"code": "insufficient_credits",
"detail": "This account has insufficient available credits."
}
Branch on status and code in your integration. Treat detail as a human-readable explanation. Record the X-Request-ID response header to help diagnose a specific request attempt.
Status codes
| Status | Code | What to do |
|---|---|---|
| 400 or 422 | invalid_request | Check the schema, number of images, USD currency, hint length, and idempotency key. |
| 401 | unauthorized | Check that the bearer credential is present, valid, and active. |
| 402 | insufficient_credits | Add available credits in Billing. |
| 403 | account_ineligible | Check your account’s status and contact support if needed. |
| 409 | idempotency_conflict | The key belongs to another payload. Recover with the original payload or use a new key for intentional new work. |
| 409 | request_in_progress | Wait for Retry-After, then retry with the same key and payload. |
| 409 | previous_request_failed | The previous operation ended without a charge. Use a new key for a new analysis. |
| 413 | request_too_large | Reduce the JSON body to 32 KiB or less. Send image URLs, not image bytes. |
| 415 | unsupported_media_type | Set Content-Type: application/json. |
| 422 | invalid_image | Check public accessibility, format, file size, and image dimensions. |
| 429 | rate_limited | Wait for Retry-After, then retry with the same key and payload using bounded backoff. |
| 502 | analysis_failed | No complete analysis was produced and no analysis credit was consumed. Start a new analysis with a new key when ready. |
| 503 | analysis_unavailable | Retry with the same key and payload using bounded backoff. |
| 503 | rate_limit_unavailable | Wait for Retry-After, then retry with the same key and payload using bounded backoff. |
Retry carefully
For transport errors, an unexpected server error, or an unreadable response, the result may be uncertain. Preserve your key and payload and follow Idempotency & retries.
Do not continuously retry validation or authentication errors. Fix the cause first. A returned Retry-After header gives the minimum delay in seconds before retrying. See Traffic limits for account sustained and burst limits.
Get help
Contact support with the request ID, approximate time, HTTP status, and error code. Include a description of what you expected. Keep API keys and private image URLs out of support messages.