Errors

Every error names the problem, says how to fix it, and links to its entry on this page.

Shape#

{
  "error": {
    "code": "op_disabled",
    "message": "op spoiler is switched off for this shop.",
    "fix": "Turn Spoiler / wing on in your shop's Storefront page, step \"Pick what you sell\".",
    "param": "op",
    "docs_url": "https://viztunr.com/docs/api/errors#op_disabled",
    "request_id": "req_AAMhe6RG_x1sfXCV"
  }
}
FieldWhat it is
codeStable, for your code to check. The list below can grow; treat an unknown code like its HTTP status
messageWhat went wrong, for the developer
fixWhat to change
paramThe request field at fault, when there is one
docs_urlThe entry for this code on this page
request_idAlso sent as the VizTunr-Request-Id header on every response. Include it when you contact support

Messages are written for developers. Show your customers your own text.

Authentication#

authentication_required#

401. The request has no Authorization header. Send Authorization: Bearer vzt_sk_....

invalid_api_key#

401. The key doesn't exist, was revoked, or isn't a vzt_sk_ key. Create a key in Settings → Developer API.

Plan and balance#

plan_required#

402. The shop has no active plan. Choose Growth or Pro in Billing.

plan_upgrade_required#

402. The shop is on Starter. The API comes with Growth and Pro; your keys work again as soon as you upgrade.

out_of_renders#

402. The balance is empty. Top up in Billing, or turn on Auto top-up. If auto top-up is on, retry in a minute.

Request#

parameter_missing#

400. A required field is missing; param names it. On uploads: the body has no file field.

parameter_invalid#

400. A field has the wrong type or value; param names it and fix says what's accepted. Also returned when the body isn't a JSON object, ref isn't an https address, label is over 120 characters, or webhook_url isn't a public https address.

upload_not_found#

404. The upload isn't an upload of this shop. Upload the photo with POST /v1/uploads and pass the id it returns.

not_found#

404. No render with this id was made through the API for this shop.

op_not_supported#

422. op isn't one of wheels, color, spoiler, exhaust.

op_disabled#

422. The try-on type is switched off for this shop. Switch it on in Storefront → Pick what you sell.

finish_not_allowed#

422. finish was sent with an op other than color. Remove it, or use op: "color".

unsupported_image_type#

422. The upload isn't JPEG, PNG, WebP, HEIC, or HEIF, or was sent with the wrong content type.

file_too_large#

413. The upload is over 10 MB.

Idempotency#

idempotency_key_reused#

409. This Idempotency-Key was already used with a different body. Use a new key for a different request.

idempotency_key_in_use#

409. A request with this key is still running. Retry after a second.

Limits and server#

rate_limited#

429. This key started its maximum number of renders in the last minute. Wait the seconds in the Retry-After header, or raise the key's limit in Settings → Developer API. See Rate limit.

internal_error#

500. Something went wrong on our side. Retry, with the same Idempotency-Key for renders. If it keeps happening, send support the request_id.

Render failure codes#

These aren't request errors: the render was accepted and later failed. They appear in render.failure.code, and the render is always given back.

CodeWhat happened
wheels_not_visibleA wheel render on a photo with no wheel face visible. Ask for a side or three-quarter photo
render_failedAnything else, for example a product image that couldn't be loaded

More in Renders.