Errors

Every error code of a request and of a task, and which to retry.

Every error has the same body and a matching HTTP status:

  "error": {

    "code": "insufficient_balance",

    "message": "Balance is too low for this task.",

    "param": null,

    "request_id": "req_…"

}

code is for a program and message is safe to show to a person. param names the field at fault when there is one, as a path such as input.resolution. Quote request_id, which is also the X-Request-Id header of every response, when you ask for help.

Request errors

A request that Opsis refuses answers with one of these. Nothing is charged and no task is created.

HTTP	Code	Example message	Retry
400	`invalid_request`	The value must be between 1 and 4.	No
400	`unsupported_combination`	This engine does not offer the 4k resolution.	No
401	`invalid_api_key`	The API key is missing, malformed, revoked or expired.	No
402	`insufficient_balance`	Balance is too low for this task.	No
402	`spend_limit_reached`	This key has reached its daily spend limit.	No
403	`account_suspended`	The account is suspended.	No
403	`email_not_verified`	Confirm your email address first.	No
403	`model_not_allowed`	This key may not use this engine.	No
403	`region_unavailable`	Opsis is not available in your country.	No
404	`not_found`	No such task.	No
409	`idempotency_conflict`	This idempotency key was used with a different request.	No
409	`task_not_cancelable`	The task has been sent to a backend and can no longer be cancelled.	No
409	`task_not_finished`	Content can be deleted once the task has a final status.	No
409	`content_gone`	The content has already expired or been deleted.	No
409	`limit_reached`	The account already holds 100 uploads.	No
403	`feature_unavailable`	New tasks are paused for now.	No
410	`model_removed`	This engine was retired.	No
413	`payload_too_large`	The body is over 6 MB.	No
429	`rate_limited`	Too many requests.	Yes, with the same Idempotency-Key
429	`concurrency_limit`	The account already has its maximum of unfinished tasks.	Yes, with the same Idempotency-Key
500	`internal_error`	Something went wrong on our side. Try again.	Yes, with the same Idempotency-Key
503	`model_unavailable`	This engine is switched off for now.	Yes, with the same Idempotency-Key
503	`dependency_unavailable`	Civitai cannot be reached, so the LoRA could not be checked. Retry with the same Idempotency-Key.	Yes, with the same Idempotency-Key
503	`text_unavailable`	The text model is not answering. Try again later.	Yes, as a new call, which is charged
422	`content_rejected`	The text model refused this request. Change the messages and try again.	No

Which to retry

Retry only 429, 500 and 503, with backoff, and reuse the same Idempotency-Key. A 429 rate_limited carries Retry-After. Do not retry the others: the same request would be refused again.

A failed check of a LoRA, or a missing linked image, is 400 invalid_request with param naming the field. If Civitai cannot be reached, the answer is 503 dependency_unavailable.

Task errors

A task that was accepted and then did not succeed has the status FAILED and one of these codes in error.code. It is refunded, except where a model charges for its own refusal.

Today no model charges for its own refusal: pricing.refusals_charged is false on every model in the model list. Read the field rather than assuming it, since a model may set it later.

Code	Meaning	What to do
`invalid_asset`	A reference image could not be downloaded at dispatch, was too large, or was not an image; or an upload it uses was deleted or had run out when the submit was built. Fix the input.	Fix the input.
`lora_unavailable`	A Civitai LoRA that passed the check at create still failed to load on the worker. Fix the input.	Fix the input.
`no_face_found`	Face swap only: no face was found in one of the two images. Fix the input.	Fix the input.
`content_rejected`	The engine refused the request. Only on the few engines that have a filter of their own. Change the prompt.	Change the prompt.
`generation_failed`	The engine failed. Retry.	Retry.
`backend_unavailable`	No backend could take the task before its deadline, or the backend it was sent to was unavailable. Retry.	Retry.
`timeout`	The attempt ran for its run_seconds without finishing, or a provider call ran out of time. Retry.	Retry.
`canceled`	The customer canceled it, or the task was still waiting when its account's closure was carried out.	Nothing to retry.

A task is tried on one backend, once. A backend failure ends it as FAILED and refunded; you submit it again. See Tasks for the statuses.

Ignore what you do not know

New codes and fields can be added without a new version. Treat an unknown code like a general failure, and ignore fields you do not use.

Video

A video task fails with the same codes. These are the video cases; Video has them with what to do.

unsupported_combination (a request error): a length the model does not offer, an aspect ratio it does not offer, or a field it does not list. Nothing is charged.
invalid_asset (a task error): the first frame could not be downloaded at the start, was too large or was not an image, or an upload it used was gone.
content_rejected and generation_failed (task errors): a model may refuse a first frame or a prompt. A refusal that Opsis recognises as one ends the task as content_rejected. Until Opsis has recorded the texts the outside providers use, a refusal from one of them can also end it as generation_failed. For a video, generation_failed reads "The engine could not produce a video." Both are refunded in full, and the same prompt and first frame will be refused again.
timeout and backend_unavailable (task errors): the clip ran out of time, or no backend took it in time. Both are refunded.
concurrency_limit (a request error): the account has the most unfinished tasks it may have. A video that is over its running limit is not an error; it waits as PENDING.