Error Handling

The API uses conventional HTTP response codes to indicate the success or failure of requests. This page documents error formats and handling strategies.

Error response formats

The format depends on where the error is produced.

Authentication and rate limit errors (401 and 429)

A small JSON object with error, message and status. The policy change endpoints, the provisioning QR code endpoint, and the device command endpoints other than lock, lost-mode, found and message, are the exception: their 429 uses the problem details format below, with code and retryable.

HTTP/1.1 429 Too Many Requests
Retry-After: 30
Content-Type: application/json

{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded for device commands on this API key. Try again later.",
  "status": 429
}

All other errors (for example 400, 403, 409, 422, 500, 502 and 503)

RFC 9457 problem details with the content type application/problem+json. Validation errors add an errors array. The policy change endpoints, the provisioning QR code endpoint, and the device command endpoints other than lock, lost-mode, found and message, add a code member to every error except 401. On the provisioning QR code endpoint, a body that is not valid JSON or has an unknown field is also an exception: its 400 has no code. The retryable member is described below.

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

{
  "type": "VALIDATION_ERROR",
  "title": "Validation Error",
  "status": 400,
  "instance": "/emm/api/v1/assets/k3x9m2pa/commands/message",
  "errors": [
    { "field": "title", "index": null, "message": "must not be blank" }
  ]
}
FieldDescription
typeError type, or about:blank
titleShort summary, such as the HTTP status phrase
statusThe HTTP status code
detailHuman-readable explanation of this error
instanceThe request path
errorsField-level validation errors, each with field, index and message (400 only)
codeA stable error code to branch on, such as not_found, forbidden or internal_error. Sent by the policy change endpoints, the provisioning QR code endpoint and the device command endpoints other than lock, lost-mode, found and message.
retryabletrue if the same request may be retried. Sent on 502 and 503 from every device command endpoint, on 429 and 500 from the command endpoints other than lock, lost-mode, found and message, and on every error that carries a code from the policy change endpoints and the provisioning QR code endpoint.

A 404 for an unknown asset or policy has an empty body. The policy change endpoints, the provisioning QR code endpoint, and the device command endpoints other than lock, lost-mode, found and message, are the exception: their 404 is problem details with code not_found.

The Device User session endpoints answer 400, 404 and 409 with application/problem+json and a code member to branch on; they send no retryable member. Two exceptions have no code: 401 and 403, and a 400 for an invalid query parameter of GET /device-user-logins. Device User sessions API

HTTP Status Codes

CodeDescription
400Invalid request parameters or malformed request body
401Missing or invalid API key
403API key doesn't have required permissions for this endpoint
404Requested resource doesn't exist
429Rate limit exceeded - retry after the specified time
500Internal server error - please contact support if persists
503Service temporarily unavailable - try again later

Device command responses

The command endpoints use status codes with special retry rules. Retrying the wrong one can deliver a command to a device twice.

202Outcome unknown. Do not resend. Check the command history first.
500Unexpected error, with code internal_error outside the lock, lost-mode, found and message endpoints. Whether the command reached the device is unknown. Check the device before retrying.
503Not sent. Safe to retry.
502The provider rejected the command. Retry only if retryable is true.
409The device cannot take this command. Retrying fails until its state changes.
422The provider refused the command. Do not retry with the same arguments.
HTTP/1.1 202 Accepted

{
  "assetId": "k3x9m2pa",
  "type": "LOCK",
  "status": "UNCONFIRMED",
  "detail": "The command's outcome is unknown. Check the device's command history (list_device_commands or GET /api/v1/assets/{assetId}/commands) before retrying; it may only appear once the device acknowledges it."
}
HTTP/1.1 503 Service Unavailable
Content-Type: application/problem+json

{
  "type": "about:blank",
  "title": "Service Unavailable",
  "status": 503,
  "detail": "Command was not sent; it is safe to retry.",
  "instance": "/emm/api/v1/assets/k3x9m2pa/commands/message",
  "retryable": true
}

Full device commands reference

Retry Strategy

Retry only when it is safe. Read requests that fail with a transient error can be retried with exponential backoff. A device command must follow the rules in the device command responses section. After a policy change or provisioning QR code error, follow its retryable field, and after an unexpected error on apply, read the proposal before proposing again.

  • For 429 errors, wait the number of seconds in the Retry-After header before retrying.
  • For 5xx errors on read requests, use exponential backoff (1s, 2s, 4s, 8s...) with jitter. For device commands, retry only a 503 (not sent) or a 502 with retryable set to true. After a 202 or a 500, check the device before sending again.
  • Set a maximum retry count (e.g., 3-5 attempts) to avoid infinite loops

Rate Limiting

When you exceed the MCP request limit, or call the lock, lost-mode, found or message endpoint over the command limit, the API returns HTTP 429 Too Many Requests with a Retry-After header and a JSON body with error, message and status. The other device command endpoints, the policy change endpoints and the provisioning QR code endpoint also send Retry-After over the same limit, but their body is problem details with code rate_limited and retryable true. When an MCP command, policy change or provisioning tool call exceeds the command limit, the result is a tool error whose text says how many seconds to wait.

Use the Retry-After header, or the seconds given in a tool error, to decide when to retry. The API does not send X-RateLimit-Limit, X-RateLimit-Remaining or X-RateLimit-Reset headers.

Validation Errors

For 400 errors caused by an invalid request body, the problem details include an errors array with one entry per invalid field. Other 400 errors, such as an invalid lastSeenBefore value, explain the problem in detail.

Error Handling Best Practices

  • Always check the HTTP status code before parsing the response body
  • Follow Retry-After on 429, and use exponential backoff for 5xx errors on read requests. For device commands, retry only a 503 or a 502 with retryable set to true, and never resend after a 202 or a 500 without checking the device first.
  • Log the HTTP status and the detail or message from the error body for debugging. Error bodies do not include timestamp or path fields.
  • Handle specific error codes differently (e.g., 401 triggers re-authentication)

Choose Your Time

Loading...
Open booking calendar