Errors

Errors come back with an HTTP status and a JSON body. type is stable and meant for code; message is meant for people and can change. Some errors add fields with details.

{
  "error": {
    "type": "insufficient_balance",
    "message": "This job costs $0.04; the balance is $0.01.",
    "price_usd": 0.04,
    "balance_usd": 0.01
  }
}

Error types

Status	Type	When	What to do
400	invalid_request	The body, query or path doesn’t match the endpoint, such as a missing user. issues lists every problem.	Fix the request.
400	invalid_input	The model’s input failed validation, such as a width that isn’t a multiple of 16. issues lists every problem.	Check the fields on the model’s page.
401	missing_api_key	No Authorization: Bearer vk_... header.	Send your API key.
401	invalid_api_key	The key is wrong or has been revoked.	Use an active key from the console.
402	insufficient_balance	The balance can’t cover the task’s price. Includes price_usd and balance_usd.	Top up in the console.
402	spend_cap_reached	The task would take this key over its monthly cap.	Wait for next month, or use a key with a higher cap.
403	account_suspended	The account has been suspended.	Contact us.
403	end_user_suspended	This user reached 10 strikes.	Don’t send more tasks for this end user.
404	not_found	No task with that id belongs to your account.	Check the id.
404	unknown_model	The model doesn’t exist.	Use an id from GET /v1/models.
409	task_finished	You tried to cancel a task that had already finished.	Nothing to do.
422	prompt_blocked	Content screening refused the prompt. Includes categories, and for strikes end_user_strikes and end_user_suspended.	Show the end user a refusal; don’t retry the same prompt.
422	reference_not_allowed	A reference image isn’t an output of your account, or was taken down. rejected lists them.	Use your own recent outputs as references.
429	too_many_declined_prompts	More than 60 prompts were refused on your account in the last minute.	Slow down and look at who is sending them.
500	internal_error	Something went wrong on our side.	Retry with the same Idempotency-Key.
503	screening_unavailable	Prompt screening couldn’t run, so the task wasn’t created and nothing was held.	Retry with backoff.

Failed tasks

A task can also be accepted and then fail. That isn’t an HTTP error: the task’s state becomes failed, its error explains why, and its hold is released. If meta.withheld is true, the output safety check withheld the images (see Output checks). Tasks that haven’t finished 30 minutes after they were created fail the same way.

Retrying

• Retry network errors, 500 and 503 with exponential backoff. Use an idempotency key so a retried POST /v1/tasks can’t create a second task.
• Don’t retry 4xx errors unchanged. They fail the same way until you change the request, the balance or the key.