Error Handling & Retries

Synchronous Errors

Errors from invalid requests are returned immediately:

{
  "success": false,
  "error": {
    "code": "ERR_INVALID_PARAMS",
    "message": "missing X-Reference-ID header"
  }
}

Code	HTTP Status	Description
ERR_INVALID_PARAMS	400	Missing or invalid parameters
ERR_UNAUTHORIZED	401	Missing or invalid API token
ERR_DEVICE_NOT_FOUND	404	cloud_id not registered
ERR_UNSUPPORTED	400	Operation not supported by this device
ERR_INTERNAL	500	Internal server error

Webhook Errors

Device errors are delivered via the webhook callback:

{
  "referenceId": "my-ref",
  "status": "failed",
  "error": {
    "code": "ERR_INTERNAL",
    "message": "device timeout"
  }
}

Common device errors:

Error Message	Meaning
device not found	Device is offline or cloud_id is wrong
device timeout	Command took longer than 30 minutes
command failed: bad_request	Device rejected the command (e.g. unsupported biometric type)

Webhook Retries

Webhook delivery uses exponential backoff:

Attempt	Delay Before Retry
1	0s (immediate)
2	1s
3	2s
4	4s
5	8s (last attempt)

After 5 failed attempts the webhook is dropped. Retry count and timeout are configurable via V2_WEBHOOK_MAX_RETRIES and V2_WEBHOOK_HTTP_TIMEOUT.

Correlation ID

The X-Reference-ID header is a correlation ID you provide. The same value is echoed back in the webhook payload so you can match acks to callbacks. It does not provide idempotency — duplicate requests with the same referenceId will execute the command twice.