Errors & retries

Failures carry a stable `code`. Match on the code, never on the message text — messages are written for people and change.

Every error response has the same shape. Branch on code, never on error — the message is written for a person and may be reworded; the code is a contract.

{
  "error": "Insufficient credit: this run needs about $0.04 and you have $0.01 available.",
  "code": "INSUFFICIENT_CREDITS",
  "requiredCents": 4,
  "availableCents": 1
}

Codes

Code	Meaning
`0`	[object Object]
`1`	[object Object]
`2`	[object Object]
`3`	[object Object]
`4`	[object Object]

Retry semantics

Status	Retry?	How
`429`	Yes	Wait for `Retry-After` seconds. Do not retry sooner — a tighter loop just burns the next window too.
`5xx`	Yes	Exponential backoff with jitter, a small bounded number of attempts.
`402`	No	Top up credit first. Retrying an unaffordable run cannot make it affordable.
`403`	No	Consent, suspension or approval. All three need a human action, not another request.
`400`	No	The request is malformed. Fix it.
`404`	No	Either the resource does not exist, or the feature is not enabled here — the two are deliberately indistinguishable.

A failed run is never charged. Work reserves its estimated cost when it starts and settles the true cost when it finishes; if it throws, the reservation is released in full. You are billed for what was processed, not for what was attempted.

Repeated submissions

Dedup runs are pure with respect to your data: the same files at the same threshold produce the same report. A retry after a network timeout is therefore safe in the sense that it cannot corrupt anything — but it is a second run and it is billed as one. Where a job id exists, poll it rather than resubmitting.

Reference generated from live API (https://api.voxelion.ai) on 2026-08-30. The endpoint list, error codes and limits on this page are produced from the API's own route table — if an endpoint is not listed here, it is not enabled on production.