External Integrations

Error Model and Observability

Canonical error envelope, correlation ID behavior, and retry guidance for external clients.

Canonical Error Envelope

{
  "error": "Human-readable message",
  "code": "MACHINE_READABLE_CODE",
  "correlationId": "uuid"
}

Validation failures may include route-specific details payloads. Correlation IDs are also returned in X-Request-ID.

Error Code Matrix

Code	HTTP	Meaning	Retryable
AUTH_HEADER_INVALID	401	Authorization header missing or malformed for Clerk-protected endpoints.	No
AUTH_TOKEN_INVALID	401	Clerk token invalid or expired.	No
AUTH_NO_ORGANIZATION	403	No org/tenant context resolved from token/header.	No
AUTHORIZATION_HEADER_MISSING	401	Device runtime call missing Authorization header.	No
AUTHORIZATION_HEADER_INVALID	401	Device runtime Authorization header not in Bearer format.	No
DEVICE_API_KEY_INVALID	401	Device API key hash not found or inactive.	No
DEVICE_API_KEY_REVOKED	401	Device API key has been revoked.	No
PROVISIONING_CODE_EXPIRED	410	Provisioning code is expired and cannot be reused.	No
PROVISIONING_CODE_ALREADY_USED	422	Provisioning code has already been activated.	No
RATE_LIMIT_EXCEEDED	429	Registration attempts exceeded per-IP threshold; honor Retry-After.	Yes
DATABASE_ERROR	500	Unhandled persistence/query failure in route operation.	Yes
REGISTRATION_ERROR	500	Device registration failed after internal compensation attempts.	Yes

Retry Guidance

Respect Retry-After for HTTP 429 responses before retrying.
Treat 5xx responses as retryable with exponential backoff and jitter.
Do not retry expired/already-used provisioning codes (410, 422).
Do not retry authentication failures until credentials or context are fixed (401/403).

Operational Tracing

Always log and propagate X-Request-ID values in client logs and support tickets. This ID maps to API-side structured logs and is the primary trace handle for incident triage.