Errors and limits
Every failure uses one envelope. The code is stable; the message is an English fallback you can show to a user.
{
"error": {
"code": "insufficient_credits",
"message": "You need more credits to generate."
}
}Statuses
| HTTP | Typical code | What to do |
|---|---|---|
| 400 | invalid_request, prompt_too_long, invalid_reference_image | Fix the request; do not retry unchanged |
| 401 | unauthorized | Check the key; do not retry in a loop |
| 402 | insufficient_credits | Top up credits; never retry |
| 403 | unauthorized | Unpaid key creation, or audio requested without premium |
| 404 | not_found | Unknown job, or not this account's |
| 409 | invalid_request | Idempotency-Key conflict; use a fresh key |
| 413 / 415 | invalid_request / unsupported_image_type | Upload a smaller JPEG, PNG or WebP |
| 429 | rate_limited | Wait for Retry-After |
| 500 / 503 | internal | Retry with backoff |
400
- Typical code
invalid_request,prompt_too_long,invalid_reference_image- What to do
- Fix the request; do not retry unchanged
401
- Typical code
unauthorized- What to do
- Check the key; do not retry in a loop
402
- Typical code
insufficient_credits- What to do
- Top up credits; never retry
403
- Typical code
unauthorized- What to do
- Unpaid key creation, or audio requested without premium
404
- Typical code
not_found- What to do
- Unknown job, or not this account's
409
- Typical code
invalid_request- What to do
Idempotency-Keyconflict; use a fresh key
413 / 415
- Typical code
invalid_request/unsupported_image_type- What to do
- Upload a smaller JPEG, PNG or WebP
429
- Typical code
rate_limited- What to do
- Wait for
Retry-After
500 / 503
- Typical code
internal- What to do
- Retry with backoff
A failed generation is a 200 job response with status: "failed" and an error object with code internal. A finished job is terminal: do not submit it again.
Retry policy
- Retry only HTTP
429,timeoutandinternalresponses. - Never retry
insufficient_credits, and never resubmit a job that already ended asfailed. - Use an
Idempotency-Keyon creates so a retry cannot charge twice. - Back off exponentially, with jitter, starting around one second.
Rate limits
Limits are per key, in fixed one-minute windows, unless noted. Defaults:
- 60 requests/minute overall.
- 10 generation creates/minute.
- 5 uploads/minute.
- 120
GET /v1/modelsrequests/minute per client IP (the route is public). - 5 API-key creations/hour per account.
A 429 carries X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset and Retry-After.
Availability
If /v1 is temporarily unavailable, every route answers 503 with code internal. Retry later with backoff.