Errors - Voyager

Every error response has the same shape, and every code has a section on this page. doc_url links straight to it. An example:

{
  "error": {
    "type": "permission",
    "code": "insufficient_credits",
    "message": "Not enough credits for this job.",
    "doc_url": "https://docs.voyager.so/api/errors#insufficient_credits",
    "request_id": "req_01JC4T6P0D2F4H6K8M0P2R4T6V",
    "retryable": false,
    "details": { "upgrade_url": "https://voyager.so/dashboard/billing", "required_hold": …, "available_credits": … }
  }
}

Field	Type	Description
`type`	`ErrorType`	Stable category to branch on.
`code`	`string`	Stable machine code; never renamed once published (x-voyager-errors lists each).
`message`	`string`	For developers. Not localized.
`doc_url`	`string`	https://docs.voyager.so/api/errors#<code>
`request_id`	`string` or `null`	Also in the X-Request-ID header; quote it to support.
`retryable`	`boolean` or `null`	Whether the same request can succeed later.
`retry_after_ms`	`integer` or `null`	How long to wait before retrying.
`param`	`string` or `null`	The request field at fault, as a path (e.g. input.resolution); set on invalid_input.
`details`	`object` or `null`	Code-specific detail, e.g. upgrade_url on a billing wall.

type is a broad category; code is the specific error and is never renamed, so branch on it. message is for developers and can change: don’t parse it. 429 responses also send Retry-After in seconds.

How to handle errors

Branch on code, not on message or the status alone.
Retry only when retryable is true, after retry_after_ms or Retry-After, with backoff, and with the same Idempotency-Key. Then a retry can never create a second job.
Billing errors (402) aren’t fixed by retrying, except credits_reloading. Show details.upgrade_url to the person who manages the workspace. Nothing was held or charged.
Log request_id on every error.

Codes come back in two ways: as an HTTP error response, or in a finished job’s error object ({code, message, details}).

Group	Code	Returned as	Retryable	Meaning
model	`invalid_request`	`400`	no	The request is not a valid model request.
	`invalid_input`	`400`	no	The model can’t take this input as sent.
	`content_policy`	`422`	no	This request was refused under the model’s content policy.
	`upstream_unavailable`	`503`	yes	The model couldn’t run this request right now.
	`rate_limited`	`429`	yes	Too many requests.
	`queue_full`	`429`	yes	Your plan’s limit of generations running at once is reached.
	`model_unavailable`	`503`	yes	This model isn’t available right now.
	`model_not_found`	`404`	no	Unknown model.
	`insufficient_credits`	`402`	no	Not enough credits for this generation.
	`paid_plan_required`	`402`	no	This model needs a paid plan.
	`model_not_in_plan`	`402`	no	This model isn’t included in your plan.
	`model_access_required`	`403`	no	This model needs access to be granted first.
	`outcome_unknown`	`503`	yes	Voyager couldn’t confirm this generation yet.
	`expired`	`410`	no	These results have expired.
	`not_found`	`404`	no	No such generation for this workspace.
	`conflict`	`409`	no	This generation can’t change from its current state.
	`forbidden`	`403`	no	This request isn’t allowed for this workspace.
	`internal_error`	`500`	no	Something went wrong on Voyager’s side.
	`catalog_unavailable`	`503`	yes	The model catalog is temporarily unavailable.
	`billing_unavailable`	`503`	yes	Your plan couldn’t be checked right now, so this paid request can’t run yet.
	`no_voyager_seat`	`402`	no	You don’t have a seat on this workspace’s Voyager plan.
	`credits_reloading`	`402`	yes	Your credits are reloading and the balance is briefly short.
	`cast_not_supported`	`422`	no	Cast works with image and video models only.
	`voice_cloning_unavailable`	`403`	no	Voice cloning isn’t available to this workspace.
	`too_many_references`	`422`	no	Too many reference files for this model and operation.
	`payload_too_large`	`413`	no	The request body is too large.
	`upload_too_large`	`413`	no	This file is over your plan’s per-file limit.
	`intake_full`	`429`	yes	Too many recent reference files are stored.
	`invalid_url`	`422`	no	That URL can’t be used: it must be a public https URL.
	`fetch_failed`	`502`	no	That URL couldn’t be downloaded.
	`unsupported_file`	`415`	no	That file isn’t a supported image, video or audio type.
api	`invalid_api_key`	`401`	no	Missing, invalid or revoked API key.
	`idempotency_conflict`	`409`	no	This Idempotency-Key was already used for a different request.
	`idempotency_in_flight`	`409`	yes	A request under this Idempotency-Key is still running; retry shortly.
	`invalid_idempotency_key`	`400`	no	Idempotency-Key must be 1-200 printable ASCII characters.
	`invalid_cursor`	`400`	no	Pass next_cursor exactly as a page returned it.
	`invalid_webhook_url`	`400`	no	webhook_url must be a public https URL.
	`method_not_allowed`	`405`	no	This method is not supported on this path.
	`account_unavailable`	`402`	no	This Voyager account is not eligible for generation.
	`plan_required_for_faces`	`403`	no	This video model needs the Ultra or GigaMax plan for a photoreal Cast character.
	`version_conflict`	`409`	no	The Cast card changed since you read it.
	`slug_taken`	`409`	no	Another Cast card in this workspace already uses that slug.
	`already_referenced`	`409`	no	That image is already a reference on this Cast card.
	`asset_in_use`	`409`	yes	The file is in use by a running job or saved in a Cast card.
	`upload_incomplete`	`409`	no	Nothing was uploaded yet.
	`cancel_unsupported`	`409`	no	This kind of job cannot be stopped once started.
	`unsupported_model`	`422`	no	This model can’t run that operation.
	`invalid_job_id`	`400`	no	Job ids look like job_…; pass one exactly as returned.
	`voice_required`	`422`	no	Choose a voice: pick one from GET /v1/voices and pass its id as input.voice_id.
	`observation_timeout`	`503`	yes	The job’s status couldn’t be read in time.
	`reference_unavailable`	`503`	yes	A reference file couldn’t be prepared right now.
job	`queue_timeout`	job `canceled`	no	The job waited in the queue too long and was canceled; nothing was charged.
	`reference_missing`	job `failed`	no	A reference file was deleted before the job started.

invalid_request

400 · type invalid_request · not retryable The request is not a valid model request.

invalid_input

400 · type invalid_request · not retryable The model can’t take this input as sent.

`details` field	Description
`field`	The input at fault, as a path (input.<name>); also in param.
`fields`	Unknown input names, when the input names fields the model does not take.

content_policy

422 · type unprocessable · not retryable This request was refused under the model’s content policy. Change the prompt or inputs; retrying it unchanged will not succeed.

`details` field	Description
`reason`	What the refusal was about. One of `copyright`, `likeness`, `minors`, `other`, `sexual`, `violence`. One of `copyright`, `likeness`, `minors`, `other`, `sexual`, `violence`.

upstream_unavailable

503 · type upstream_error · retryable The model couldn’t run this request right now. You were not charged; try again shortly.

rate_limited

429 · type rate_limited · retryable Too many requests. Retry after the indicated delay.

queue_full

429 · type rate_limited · retryable Your plan’s limit of generations running at once is reached. Retry when one finishes.

`details` field	Description
`upgrade_url`	Where to upgrade the plan or add credits.

model_unavailable

503 · type upstream_error · retryable This model isn’t available right now.

model_not_found

404 · type not_found · not retryable Unknown model.

insufficient_credits

402 · type permission · not retryable Not enough credits for this generation.

`details` field	Description
`upgrade_url`	Where to upgrade the plan or add credits.

paid_plan_required

402 · type permission · not retryable This model needs a paid plan.

`details` field	Description
`upgrade_url`	Where to upgrade the plan or add credits.

model_not_in_plan

402 · type permission · not retryable This model isn’t included in your plan.

`details` field	Description
`upgrade_url`	Where to upgrade the plan or add credits.

model_access_required

403 · type permission · not retryable This model needs access to be granted first.

outcome_unknown

503 · type upstream_error · retryable Voyager couldn’t confirm this generation yet. Ask for its status again; never submit it again, or it may be charged twice.

`details` field	Description
`support_ref`	Quote it to support.

expired

410 · type not_found · not retryable These results have expired.

not_found

404 · type not_found · not retryable No such generation for this workspace.

conflict

409 · type conflict · not retryable This generation can’t change from its current state.

forbidden

403 · type permission · not retryable This request isn’t allowed for this workspace.

internal_error

500 · type internal_error · not retryable Something went wrong on Voyager’s side.

catalog_unavailable

503 · type upstream_error · retryable The model catalog is temporarily unavailable. Retry shortly.

billing_unavailable

503 · type upstream_error · retryable Your plan couldn’t be checked right now, so this paid request can’t run yet. Retry shortly.

no_voyager_seat

402 · type permission · not retryable You don’t have a seat on this workspace’s Voyager plan.

credits_reloading

402 · type permission · retryable Your credits are reloading and the balance is briefly short. Retry shortly.

cast_not_supported

422 · type unprocessable · not retryable Cast works with image and video models only.

voice_cloning_unavailable

403 · type permission · not retryable Voice cloning isn’t available to this workspace.

too_many_references

422 · type unprocessable · not retryable Too many reference files for this model and operation.

payload_too_large

413 · type invalid_request · not retryable The request body is too large.

upload_too_large

413 · type invalid_request · not retryable This file is over your plan’s per-file limit.

intake_full

429 · type rate_limited · retryable Too many recent reference files are stored. Delete some, or wait: they’re kept 7 days.

invalid_url

422 · type unprocessable · not retryable That URL can’t be used: it must be a public https URL.

fetch_failed

502 · type upstream_error · not retryable That URL couldn’t be downloaded. Check it is live and public.

unsupported_file

415 · type invalid_request · not retryable That file isn’t a supported image, video or audio type.

invalid_api_key

401 · type authentication · not retryable Missing, invalid or revoked API key.

idempotency_conflict

409 · type idempotency_conflict · not retryable This Idempotency-Key was already used for a different request.

idempotency_in_flight

409 · type conflict · retryable A request under this Idempotency-Key is still running; retry shortly.

invalid_idempotency_key

400 · type invalid_request · not retryable Idempotency-Key must be 1-200 printable ASCII characters.

invalid_cursor

400 · type invalid_request · not retryable Pass next_cursor exactly as a page returned it.

invalid_webhook_url

400 · type invalid_request · not retryable webhook_url must be a public https URL.

method_not_allowed

405 · type invalid_request · not retryable This method is not supported on this path.

account_unavailable

402 · type permission · not retryable This Voyager account is not eligible for generation.

plan_required_for_faces

403 · type permission · not retryable This video model needs the Ultra or GigaMax plan for a photoreal Cast character. Use a stylized character or a different video model.

version_conflict

409 · type conflict · not retryable The Cast card changed since you read it. Read it again and retry with its current version.

slug_taken

409 · type conflict · not retryable Another Cast card in this workspace already uses that slug.

already_referenced

409 · type conflict · not retryable That image is already a reference on this Cast card.

asset_in_use

409 · type conflict · retryable The file is in use by a running job or saved in a Cast card. Delete it after the job ends, or remove it from the card first.

upload_incomplete

409 · type conflict · not retryable Nothing was uploaded yet. PUT the file to upload_url first.

cancel_unsupported

409 · type conflict · not retryable This kind of job cannot be stopped once started. It finishes on its own.

unsupported_model

422 · type unprocessable · not retryable This model can’t run that operation. GET /v1/models/{id} lists the operations it runs.

invalid_job_id

400 · type invalid_request · not retryable Job ids look like job_…; pass one exactly as returned.

voice_required

422 · type unprocessable · not retryable Choose a voice: pick one from GET /v1/voices and pass its id as input.voice_id.

observation_timeout

503 · type upstream_error · retryable The job’s status couldn’t be read in time. Ask again with the same id; never submit it again.

reference_unavailable

503 · type upstream_error · retryable A reference file couldn’t be prepared right now. Retry shortly.

queue_timeout

On a finished job: status canceled · not retryable The job waited in the queue too long and was canceled; nothing was charged.

reference_missing

On a finished job: status failed · not retryable A reference file was deleted before the job started. Nothing was charged.

Cloud machines errors

The cloud machines endpoints (/v1/machines) use the same envelope with UPPER_SNAKE codes, such as PLAN_REQUIRED, INSUFFICIENT_CREDITS and MACHINE_NOT_READY. They’re listed in the cloud machines reference.

​How to handle errors

​invalid_request

​invalid_input

​content_policy

​upstream_unavailable

​rate_limited

​queue_full

​model_unavailable

​model_not_found

​insufficient_credits

​paid_plan_required

​model_not_in_plan

​model_access_required

​outcome_unknown

​expired

​not_found

​conflict

​forbidden

​internal_error

​catalog_unavailable

​billing_unavailable

​no_voyager_seat

​credits_reloading

​cast_not_supported

​voice_cloning_unavailable

​too_many_references

​payload_too_large

​upload_too_large

​intake_full

​invalid_url

​fetch_failed

​unsupported_file

​invalid_api_key

​idempotency_conflict

​idempotency_in_flight

​invalid_idempotency_key

​invalid_cursor

​invalid_webhook_url

​method_not_allowed

​account_unavailable

​plan_required_for_faces

​version_conflict

​slug_taken

​already_referenced

​asset_in_use

​upload_incomplete

​cancel_unsupported

​unsupported_model

​invalid_job_id

​voice_required

​observation_timeout

​reference_unavailable

​queue_timeout

​reference_missing

​Cloud machines errors