API reference
Errors
HTTP status codes, the error body, and when a retry helps.
Errors use real HTTP status codes and this body:
{
"error": {
"code": "insufficient_balance",
"message": "Insufficient balance. Please top up your account.",
"type": "invalid_request_error"
}
}type is server_error for 5xx errors and invalid_request_error otherwise.
- Errors at submit time (4xx): no task is created and nothing is charged.
- Failures while running: the task's
statusbecomesfailed, itserrorhas the samecodeandmessage, and the charge is refunded in full.
| HTTP | code | Meaning |
|---|---|---|
| 400 | invalid_request | The request body or a parameter is invalid; the message says which. |
| 400 | route_not_offered | The requested route does not offer this model. |
| 400 | no_route_selected | Your route settings leave no route for this model. |
| 400 | price_above_max | Every selected route costs more than your maximum price. |
| 400 | unsupported_parameters | No selected route supports this combination of parameters. |
| 400 | content_policy_violation | Content moderation refused the request. |
| 503 | moderation_pending | docs.err_moderation_pending |
| 503 | moderation_unavailable | docs.err_moderation_unavailable |
| 401 | unauthorized | The API key is missing or invalid. |
| 402 | insufficient_balance | Your balance is too low. Top up and try again. |
| 402 | key_quota_exceeded | This API key reached its spending limit. |
| 403 | forbidden | This key may not use this model, or not from this IP address. |
| 403 | account_blocked | API access for this account is suspended. |
| 404 | model_not_found | No such model is on sale. |
| 404 | task_not_found | No such task in your account. |
| 404 | file_not_found | No such uploaded file, or it expired. |
| 409 | idempotency_conflict | This Idempotency-Key was used with a different request. |
| 429 | rate_limited | Too many requests. Slow down. |
| 429 | too_many_tasks | Too many tasks are waiting. Retry later. |
| 502 | generation_failed | Generation failed. You were not charged. |
| 503 | no_available_route | No route can serve this model right now. You were not charged. |
| 504 | timeout | Generation timed out. You were not charged. |
| 500 | internal_error | Something went wrong on our side. |
Content refusals
A content_policy_violation also has a category saying what kind of content was refused, so you can tell your users what to change. Its message names it too:
{
"error": {
"code": "content_policy_violation",
"message": "The request was rejected by content moderation: possible nudity or sexual content.",
"type": "invalid_request_error",
"category": "sexual"
}
}| category | Refused for |
| ------------- | ------------------------------------------- |
| sexual | Nudity or sexual content |
| suggestive | Lightly sexual or provocative themes |
| minors | How minors are depicted |
| violence | Violent content |
| harassment | Harassment, discrimination or bullying |
| fraud | Fraud or scams |
| third_party | Similarity to third-party content |
| identity | Face swaps or impersonating a real person |
| other | Anything else, or a reason we couldn't tell |
More categories may be added; treat an unknown one as other.
moderation_unavailable (503) is not a refusal: the safety check itself could not run. Nothing was charged; retry later.
When to retry
- 429: wait a moment, then send fewer requests.
- 502, 503, 504: submit a new task. The failed one was refunded.
- 400, 402, 403, 404: fix the request, top up or change the key's settings first; retrying as is won't help.