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"
}
}
| Field | What it is |
|---|---|
code | Stable, for your code to check. The list below can grow; treat an unknown code like its HTTP status |
message | What went wrong, for the developer |
fix | What to change |
param | The request field at fault, when there is one |
docs_url | The entry for this code on this page |
request_id | Also 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.
| Code | What happened |
|---|---|
wheels_not_visible | A wheel render on a photo with no wheel face visible. Ask for a side or three-quarter photo |
render_failed | Anything else, for example a product image that couldn't be loaded |
More in Renders.