Reference
Error codes
An error is HTTP 4xx or 5xx with application/problem+json (RFC 9457) and a machine code in the code field: branch on it, not on the text.
Error format
problem+json
{
"type": "about:blank",
"title": "Not Found",
"status": 404,
"detail": "Register 42 not found",
"code": "DEVICE_NOT_FOUND"
}Codes
| HTTP | code | When |
|---|---|---|
| 400 | INVALID_REQUEST | Invalid JSON or parameters; what is wrong is in detail |
| 401 | UNAUTHORIZED | Missing or wrong X-Api-Key |
| 402 | TRIAL_LIMIT | Trial plan: more receipts this month than the limit — subscribe in the cabinet |
| 403 | FORBIDDEN | The action is not available to this key |
| 403 | KEY_READ_ONLY | A read-only key or sign-in: register changes, commands, the proxy (except GET) and receipts are unavailable |
| 403 | DEVICE_DISABLED | The register is disabled in the account (PATCH /api/v1/devices/{id} disabled=true): commands and the proxy are not passed; for a receipt — 409 |
| 404 | DEVICE_NOT_FOUND | No such register or it belongs to another account |
| 404 | NOT_FOUND | No such receipt or address |
| 409 | IDEMPOTENCY_KEY_REUSED | The key was already used for another receipt |
| 429 | RATE_LIMITED | Agent request limit — wait Retry-After |
| 503 | NOT_CONNECTED | The register is offline (command or proxy); Retry-After — when to retry |
| 504 | TIMEOUT | The register did not answer — retry with the same idempotency key |
Agent proxy errors (/agent/api/v1/** and commands) also carry the X-Hw-Proxy-Error header — see Agent API → Through the cloud.