Error Model

Scope

Every Open Platform endpoint under /api/v1/open/ follows the same error envelope.

{
  "code": "VALIDATION_FAILED",
  "message": "invalid request payload",
  "request_id": "req-123"
}

code — Stable error code (string or numeric, see tables below).
message — Short caller-facing description.
request_id — Platform-issued trace ID for this call. Include it when contacting support.

code	HTTP	Description
`INVALID_REQUEST_BODY`	400	JSON request body cannot be parsed.
`VALIDATION_FAILED`	400	Required field missing, invalid type, non-object JSON payload, or out-of-range value.
`IDEMPOTENCY_CONFLICT`	409	The `idempotency_key` was reused with a different request body.
`COMMAND_NOT_FOUND`	404	`command_id` does not exist.
`DEVICE_REQUEST_NOT_FOUND`	404	`request_id` does not exist.
`UNSUPPORTED_VENDOR`	400	Vendor is not registered for 001 command acceptance.
`UNSUPPORTED_COMMAND`	400	Command type is unsupported or outside trusted capability scope for 001 command acceptance.
`OBJECT_POLICY_DENIED`	403	Object presign request does not satisfy tenant resource policy.
`OBJECT_SIGNING_FAILED`	500	Object storage URL signing failed.
`CALLBACK_NOT_FOUND`	404	Callback endpoint or subscription does not exist.
`NATS_PRINCIPAL_CONFLICT`	409	NATS principal already exists or conflicts with an active mapping.
`NATS_SUBJECT_POLICY_INVALID`	400	NATS subject is not tenant-prefixed or violates subject policy.
`INTERNAL_ERROR`	500	Platform internal error — include the `request_id` when contacting support.

Authentication failures also use the standard envelope.

code	HTTP	Description
`UNAUTHORIZED`	401	Unauthenticated: missing API ID, timestamp, nonce, signature, or usable credential.
`SIGNATURE_INVALID`	401	Signature mismatch. Likely an API Key mismatch, malformed canonical string, or proxy-mutated body.
`TIMESTAMP_EXPIRED`	401	`X-Api-Timestamp` is outside the allowed skew window.
`NONCE_REPLAYED`	401	Nonce was reused within the replay window.
`FORBIDDEN`	403	Current API client lacks tenant-domain authorization.
`TENANT_NOT_FOUND`	401	No active tenant can be resolved, or the tenant is disabled/deleted.
`TENANT_BINDING_INVALID`	403	API client is not validly bound to the tenant.

INVALID_REQUEST_BODY / VALIDATION_FAILED / IDEMPOTENCY_CONFLICT — Fix the request and retry.
*_NOT_FOUND — Check the ID spelling and that the resource belongs to the current API client.
FORBIDDEN — Have the platform admin verify the API key’s tenant-domain scope grants.
INTERNAL_ERROR — Always escalate with request_id; do not retry blindly.

Business error:

{
  "code": "UNSUPPORTED_VENDOR",
  "message": "vendor is not supported",
  "request_id": "req-unsupported"
}

Authentication error:

{
  "code": "SIGNATURE_INVALID",
  "message": "invalid signature",
  "request_id": "req-signature"
}