Error Codes

The API uses standard HTTP status codes. Error responses include a JSON body with details when available.

HTTP Status Codes

200Success

Request accepted. For mutating endpoints, a task has been created.

{ "task_id": "..." }

400Bad Request

Validation failed. Check the errors array for specific field issues.

{ "errors": [{ "msg": "..." }] }

401Unauthorized

Invalid, missing, or revoked API key.

{}

402Payment Required

Your account doesn't have enough credits for this operation.

{ "errors": [{ "msg": "Insufficient credits" }] }

429Too Many Requests

You've exceeded the rate limit for your plan. Back off and retry.

{ "errors": [{ "msg": "Rate limit exceeded" }] }

500Internal Server Error

Something went wrong on our end. If this persists, contact support.

{}

When the API returns a 400 error, the response includes an errors array with one or more error objects:

{
  "errors": [
    { "msg": "prompt is required" },
    { "msg": "aspect_ratio must be a valid ratio (e.g., 16:9)" }
  ]
}

Error Message	Cause
prompt is required	Missing prompt field on /imagine or /shorten.
parent_task_id is required	Missing parent task reference on action endpoints.
parent_task_id not found	The referenced task doesn't exist or belongs to another account.
parent task is not finished	Trying to act on a task that hasn't completed yet.
index must be 1, 2, 3, or 4	Invalid grid position on /upscale-1x or /variations.
image_urls must contain 2-5 URLs	Wrong number of images for /blend.
task_ids must contain 2-20 IDs	Wrong number of IDs for /fetch-many.

Rate limits depend on your subscription plan. When you hit the limit, the API returns a429 status. Use exponential backoff when retrying.