Skip to content
VestiarionDocs

Get started

Errors

The error codes, their HTTP statuses and the error body.

A request that fails answers with an HTTP status and a JSON body that names the error with a code. Branch on the code, not on the message: the codes are a closed set, and the message is written for a person.

The error body

json
{"error":{"code":"invalid_request","message":"riskLevel must be one of unscreened, clear, medium, high."}}
  • error.code is one of the codes below.
  • error.message says what went wrong. For invalid_request it names the parameter and, for a filter, the values it accepts. It never carries implementation details such as a database error.

Codes

HTTPCodeMeaningRetry?
400invalid_requestAn invalid limit or cursor, a filter value outside its allowed values, or a request body that does not validate. The message names the parameter or the field, and lists the accepted values.No. Fix the request.
401unauthorizedNo key, or a malformed, unknown or revoked one: "A valid API key is required."No. Check the key.
403forbiddenThe key's scopes do not cover this route: "This key cannot do that." Or, on a write, the person who created the key can no longer add records: "This key's issuer can no longer add records in this workspace."No.
404not_foundThe requested resource does not exist in the key's workspace.No.
409conflictThe Idempotency-Key was already used for a different request, or the first request with it is still being handled.Not with that key. Send a new request with a new key, or wait and repeat the first one unchanged.
429rate_limitedToo many requests; wait as long as Retry-After says before trying again.Yes, after Retry-After seconds.
503unavailableA service the request depends on is unavailable.Yes, with backoff.
500internalAn unexpected server error. Implementation details are not exposed.Yes, with backoff, a few times.

Each reference page lists, under Errors, the codes that endpoint can return.

Which errors to retry

  • Do not retry a 400, 401, 403 or 404 unchanged: the same request gets the same answer.
  • Retry a 429, 503 or 500 with exponential backoff: wait, then double the wait each time, with some random jitter, and give up after a few attempts. On a 429, wait at least as long as the Retry-After header says. Limits says when these codes can occur today.
  • A 401 after a 500 is about the key; a 500 alone is not. Never discard a key because of a 500.

Errors outside the envelope

Every /api/v1 error uses the body above. An error from outside /api/v1, such as a request for a path that does not exist, is not an API error and does not have that body. Check the status code before you read error.code.