Response & error codes

Every request to the Edge API returns a standard HTTP status code. This page lists the codes the API returns, what each one means, and the conditions that trigger it.

Response format

A successful call returns the standard envelope — an HTTP 200 with a body that wraps the result in code, msg, and data.

Error responses do not use that envelope. A failed call returns the relevant HTTP status with a body containing a single detail field. Read the HTTP status code, not the body, to decide whether a call succeeded.

Success — 200 (BaseResponse envelope)

{
  "code": 200,
  "msg": "Success",
  "data": { /* … present only on endpoints that return a payload */ }
}

Error — 4xx / 5xx (single message)

{
  "detail": "No related transaction found, transaction_id: …"
}

One exception: a 422 validation failure returns detail as an array of field-level errors, one entry per invalid field. Each entry names the field in loc, with a human-readable msg and a machine-readable type.

Validation error — 422 (e.g. item-added with quantity omitted and a non-numeric price)

{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "quantity"],
      "msg": "Field required"
    },
    {
      "type": "float_parsing",
      "loc": ["body", "price"],
      "msg": "Input should be a valid number"
    }
  ]
}

Status codes

Success — 2xx

Status	When it's returned	Where
200 OK	The request succeeded. The body follows the { code, msg, data } envelope; data is present only on endpoints that return a payload.	All

Client errors — 4xx

Status	When it's returned	Where
400 Bad Request	The transaction can't accept the action: no transaction matches the transaction_id, the transaction is already finalized, or it has not been started yet. Starting a transaction also fails this way if its transaction_id was already used on this SCO — even by an earlier transaction that has since finished or been abandoned — until it's released with POST …/transaction-reset.	Item, Transaction, State, Alert
401 Unauthorized	Device registration failed because the client_id or client_secret is incorrect.	Auth
403 Forbidden	The token header is missing, expired, or invalid. Applies to every token-gated call — that is, all endpoints except device-register, which authenticates with client_id/client_secret instead. Obtain a fresh token via device registration and retry.	State, Transaction, Alert, Item, Multimedia
404 Not Found	The referenced resource doesn't exist — an alert, a transaction, or a stored video/image.	Alert, Transaction, Multimedia
422 Unprocessable Entity	The request body failed validation — a required field is missing or has the wrong type. detail is an array listing each invalid field.	All
429 Too Many Requests	A rate limit was exceeded for this SCO or across the box. Back off and retry after the window. See rate limits for the per-endpoint thresholds.	Auth, State, Transaction, Alert, Item

Server errors — 5xx

Status	When it's returned	Where
500 Internal Server Error	An unexpected error occurred while handling the request. The response has no structured body. Safe to retry; if it persists, escalate.	All
503 Service Unavailable	The sco_id in the request path has no camera mapping on this box, so the unit can't be served. This points to a configuration gap, not a transient fault.	Item, Transaction, State, Alert

Endpoint-specific notes

Rate limits (429)

Most write endpoints are rate-limited; reads, item updates, finalized prices, and alert updates are not. Each limit is counted over a rolling 60-second window, both per SCO (keyed on the sco_id in the path) and across the whole box.

Endpoint	Per SCO / 60s	Box-wide / 60s
POST …/device-register	5	50
POST …/states	30	300
POST …/weighting-scale-not-matched	30	300
POST …/transaction-started	30	300
POST …/transaction-completed	30	300
POST …/transaction-reset	30	300
POST …/scan-started	30	300
POST …/scan-completed	30	300
POST …/item-added	120	1200
POST …/item-removed	120	1200

Not found (404) resources

The resource that's missing depends on the endpoint:

• Alert — the alert being updated doesn't exist.
• Transaction — the requested transaction doesn't exist.
• Video / image — the requested media file isn't on the box.

note

A wrong client_id/client_secret at device registration returns 401. A missing or expired session token on any other call returns 403.