Errors
The CHeKT API uses standard HTTP status codes plus a structured JSON envelope. You get a stable code to switch on, a human message for logs, and an optional request_id for support tickets.
Error envelope
{
"error": {
"code": "device_not_found",
"message": "No device with that ID exists on this dealer.",
"request_id": "req_91kxl2",
"field": "device_id"
}
}
Status codes
| Status | Meaning | What to do |
|---|---|---|
| 400 | Bad request | Inspect error.field, validate input, retry. |
| 401 | Unauthorized | Refresh or rotate your API key. |
| 403 | Forbidden | Add the missing permission to your app. |
| 404 | Not found | Verify the resource ID and dealer scope. |
| 409 | Conflict | Retry after refreshing local state. |
| 422 | Validation failed | Surface error.field to the user. |
| 429 | Rate limited | Back off — see rate limits. |
| 5xx | Server error | Safe to retry with backoff. Open a ticket if it persists. |
Common error codes
invalid_api_key— token missing, expired, or revoked.permission_denied— your app lacks the required scope.device_not_found— the device ID doesn't exist under this dealer.webhook_signature_invalid— your verification failed; check the signing secret.idempotency_conflict— same idempotency key used with different payload.
Always log the request_id
When you open a support ticket, the request_id lets us trace exactly which request misbehaved. Log it on every 4xx and 5xx.