Errors

Every non-2xx response from protected /v1/* endpoints returns a flat JSON body.

Response Schema

Field	Type	Required	Description
`code`	`string`	Yes	Stable, documented, `SCREAMING_SNAKE_CASE` machine-readable error code. Branch on this field, not on `message`.
`message`	`string`	Yes	Human-readable explanation, safe to display to end users. Messages may be reworded between releases; do not pattern-match on them.
`status`	`integer`	Yes	Mirrors the HTTP status code.
`request_id`	`string (ULID)`	Yes	Unique request identifier. Also returned in the `X-Request-Id` response header. If you send `X-Request-Id` on the request, we echo it back; otherwise we generate one.
`docs_url`	`string`	No	Deep link to the relevant error code in the public docs.
`details`	`array<object>`	No	Present for `422` validation errors and any response with multiple sub-issues. Each element has `{ "field": string, "issue": string }`. This field is empty or absent for single-issue errors.

Endpoint-specific error codes are documented alongside each operation in the API reference. This page describes the shared error format and the HTTP status codes used across the API.

Examples

Simple 400 response:

{
  "code": "INVALID_REQUEST",
  "message": "The request could not be processed.",
  "status": 400,
  "request_id": "01HXJ8K2M5N6P7Q8R9S0T1V2W3",
  "docs_url": "https://docs.vizit.com/api/errors/INVALID_REQUEST",
  "details": []
}

Validation 422 response:

{
  "code": "VALIDATION_ERROR",
  "message": "The request body failed validation.",
  "status": 422,
  "request_id": "01HXJ8K2M5N6P7Q8R9S0T1V2W3",
  "docs_url": "https://docs.vizit.com/api/errors/VALIDATION_ERROR",
  "details": [
    {
      "field": "image_url",
      "issue": "must be an HTTP or HTTPS URL"
    },
    {
      "field": "product_category_id",
      "issue": "must be a valid UUID"
    }
  ]
}

Headers

Header	When present	Description
`X-Request-Id`	Always	Request identifier for this response. If you send one on the request, we echo it back.
`Retry-After`	`429` and sometimes `503`	Number of seconds to wait before retrying.

HTTP Status Codes

The API uses these response status codes:

Status Code	Meaning	Description
`200`	OK	The request succeeded.
`202`	Accepted	The request was accepted for asynchronous processing.
`400`	Bad Request	The request was malformed or failed a request-level rule.
`401`	Unauthorized	The request did not include valid authentication credentials.
`403`	Forbidden	The caller is authenticated but not permitted to perform the operation.
`404`	Not Found	The resource does not exist or is not visible to this caller.
`409`	Conflict	The request conflicts with the current state of the resource.
`422`	Unprocessable Entity	The request failed schema or field-level validation.
`429`	Too Many Requests	The caller exceeded the rate limit.
`500`	Internal Server Error	An unexpected server-side error occurred.
`502`	Bad Gateway	A dependency returned an invalid response.
`503`	Service Unavailable	The API is temporarily unavailable.
`504`	Gateway Timeout	A dependency did not respond in time.

Client Guidance

Branch on code, never on message.
Retry 429 and 5xx responses with exponential backoff. Do not retry other 4xx responses until you have fixed the request.
When contacting support, include request_id and the UTC time of the request.
Error codes are part of the /v1/* contract. New codes may be added over time, and operation-specific codes are documented in the API reference.

Response Schema

Examples

Headers

HTTP Status Codes

Client Guidance

On this page