Scannable Docs
Get started

Errors

The error envelope, the code for each status, and when to retry.

Every error comes back in one envelope, whatever the endpoint:

Error envelope
{
  "error": {
    "code": "not_found",
    "message": "Item not found",
    "request_id": "req_01j9x4m2k7qv3n8r5t6w0y1z2a"
  }
}
FieldMeaning
codeA stable, machine-readable code. Branch on it, never on message.
messageA summary for people. The wording can change at any time.
fieldsOn a validation failure, one entry per problem. See Invalid requests.
detailsPresent only when there is more to say, such as the scopes a key lacks.
hintPresent when the error has a known remedy, such as which API to use instead.
request_idThe id of this request. Every response also carries it in the X-Request-Id header.

Log request_id with every failed call. Quote it when you contact support@scannable.io, so we can find the request.

Status codes

Each status has one code, except 403, which has two.

StatuscodeMeaningWhat to do
400validation_failedA query parameter or cursor is wrong, or the list doesn't know it.Read fields, then fix the request. Retrying it unchanged fails again.
401unauthorizedThe API key is missing, invalid, expired or revoked.See Authentication.
403forbidden_scopeThe key lacks a scope, or your role or plan doesn't allow this.Read details.required for missing scopes.
403not_an_equipment_ownerThe key belongs to a manufacturer organisation.Use the manufacturer API. hint says so.
404not_foundNo resource with this identifier is in your organisation.Check the identifier.
429rate_limitedYou sent too many requests.Wait for the number of seconds in Retry-After. See Rate limits.
500internalSomething failed on our side. The message is always generic.Retry with backoff.
503service_unavailableA service we depend on could not be reached.Retry after a short wait.

A 304 Not Modified is not an error. It answers a request that sent If-None-Match. See Skip unchanged pages.

Invalid requests

Every validation failure is a 400 with code: "validation_failed". fields names each problem: the query parameter, and what is wrong with it. One request can fail on several parameters at once.

Request
curl "https://api.scannable.io/v1/items?status=broken&limit=500&offest=20" \
  -H "Authorization: Bearer $SCANNABLE_API_KEY"
400 for invalid query parameters
{
  "error": {
    "code": "validation_failed",
    "message": "Validation failed.",
    "details": ["Unknown parameter.", "Invalid limit.", "Invalid status."],
    "fields": [
      { "field": "offest", "message": "Unknown parameter." },
      { "field": "limit", "message": "Invalid limit." },
      { "field": "status", "message": "Invalid status." }
    ],
    "request_id": "req_01j9x4m2k7qv3n8r5t6w0y1z2a"
  }
}

Read fields, not details. details repeats the messages without the parameter names.

A parameter the list doesn't know reads Unknown parameter.. The API refuses it rather than ignore it, so a misspelled filter never returns unfiltered results.

A bad cursor is a field error too. fields names cursor when the list didn't issue it, or when you sent it with other filters than the request that did.

An identifier with the wrong prefix gives 400 in a filter, such as folder_id=label_…, and 404 in the path, such as /v1/items/folder_….

Retry safely

  • Retry only 429, 500 and 503, with exponential backoff. For a 429, wait at least Retry-After seconds.
  • Don't retry any other 4xx. Fix the request instead.
  • Ignore fields you don't recognise. New fields and new code values can appear in any response.

On this page