Errors
The error envelope, the code for each status, and when to retry.
Every error comes back in one envelope, whatever the endpoint:
{
"error": {
"code": "not_found",
"message": "Item not found",
"request_id": "req_01j9x4m2k7qv3n8r5t6w0y1z2a"
}
}| Field | Meaning |
|---|---|
code | A stable, machine-readable code. Branch on it, never on message. |
message | A summary for people. The wording can change at any time. |
fields | On a validation failure, one entry per problem. See Invalid requests. |
details | Present only when there is more to say, such as the scopes a key lacks. |
hint | Present when the error has a known remedy, such as which API to use instead. |
request_id | The 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.
| Status | code | Meaning | What to do |
|---|---|---|---|
400 | validation_failed | A query parameter or cursor is wrong, or the list doesn't know it. | Read fields, then fix the request. Retrying it unchanged fails again. |
401 | unauthorized | The API key is missing, invalid, expired or revoked. | See Authentication. |
403 | forbidden_scope | The key lacks a scope, or your role or plan doesn't allow this. | Read details.required for missing scopes. |
403 | not_an_equipment_owner | The key belongs to a manufacturer organisation. | Use the manufacturer API. hint says so. |
404 | not_found | No resource with this identifier is in your organisation. | Check the identifier. |
429 | rate_limited | You sent too many requests. | Wait for the number of seconds in Retry-After. See Rate limits. |
500 | internal | Something failed on our side. The message is always generic. | Retry with backoff. |
503 | service_unavailable | A 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.
curl "https://api.scannable.io/v1/items?status=broken&limit=500&offest=20" \
-H "Authorization: Bearer $SCANNABLE_API_KEY"{
"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,500and503, with exponential backoff. For a429, wait at leastRetry-Afterseconds. - Don't retry any other
4xx. Fix the request instead. - Ignore fields you don't recognise. New fields and new
codevalues can appear in any response.