Errors
Last updated: 2026-10-22
A request that is not accepted returns a non-2xx status and a JSON error body. A rejected request creates no task and costs nothing.
{
"error": {
"code": "insufficient_credits",
"message": "There are not enough available credits."
},
"request_id": "5b0d2f4e-1c3a-4e6b-8d7f-9a0b1c2d3e4f"
}
| Field | Type | Notes |
|---|---|---|
error.code | string | Stable, machine-readable code; branch on this. |
error.message | string | Human-readable description; may change. |
request_id | string | Also in the X-Request-Id header. Include it when you contact support. |
Error codes
| HTTP | error.code | Meaning and what to do |
|---|---|---|
| 400 | invalid_request | Body is not valid JSON, has unknown, null or duplicate fields, Content-Type is not application/json, or the Idempotency-Key is malformed. Fix the request. |
| 401 | invalid_api_key | Missing, malformed or revoked API key. |
| 402 | insufficient_credits | No credits available. Buy credits or a plan. |
| 404 | prediction_not_found | No such task in this account. |
| 404 | not_found | Unknown endpoint. |
| 409 | idempotency_conflict | This Idempotency-Key was used with a different input. Use a new key for a new task. |
| 413 | request_too_large | Request body over 64 KiB. |
| 422 | invalid_image_url | The image URL is not an acceptable public HTTPS URL. |
| 429 | inflight_limit_exceeded | 50 tasks of this account are already waiting or processing. Submit again when some finish. |
| 429 | rate_limited | Too many queries. Retry after the Retry-After seconds. |
| 503 | temporarily_unavailable | Temporary failure. For a submission the task may or may not have been accepted — retry with the same Idempotency-Key and input. |
A task that is accepted and later fails is not an error response: the task's status becomes "failed" and its error explains why. See Get task details.
Retries and idempotency
A timeout, a dropped connection or a 503 can leave you unsure whether a submission was accepted. Idempotency keys make retrying safe.
- Send a unique
Idempotency-Keywith each image you want checked, and store it with your own record. - Retrying with the same key and the same input — image URL including its query string, model and policy — returns the original task with
200 OKandIdempotent-Replayed: true. No new task is created and nothing is charged, even if that task failed or your balance is now zero. - The same key with a different input returns
409 idempotency_conflict. - Keys belong to the account and are shared by all its API keys.
- Without a key, every submission creates a new task and costs a credit, so a blind retry may charge twice.
- Once you have a task ID, query that task instead of submitting again.