Error Codes – Optra

All errors follow a consistent envelope. The code field is a machine-readable string you can match programmatically; message is human-readable context.

{
  "error": {
    "code": "DEVICE_NOT_FOUND",
    "message": "No device with id 'dev_xyz' exists in this organisation.",
    "request_id": "req_7f3a9b"
  }
}

Authentication Errors (401 / 403)

Code	HTTP	Cause & Fix
UNAUTHORIZED	401	Missing or malformed `Authorization` header. Check your API key.
TOKEN_EXPIRED	401	OAuth token has expired. Request a new access token.
FORBIDDEN	403	Key lacks the required scope. Check your key's permissions.

Resource Errors (404 / 409)

Code	HTTP	Cause & Fix
DEVICE_NOT_FOUND	404	Device ID does not exist or belongs to another organisation.
RULE_NOT_FOUND	404	Rule ID does not exist.
DEVICE_ALREADY_EXISTS	409	A device with this serial is already registered.

Validation Errors (422)

Code	HTTP	Cause & Fix
VALIDATION_ERROR	422	Request body failed schema validation. See `details` array for field-level errors.
INVALID_DATE_RANGE	422	`from` is after `to`, or range exceeds the maximum 90-day window.

Server Errors (5xx)

Code	HTTP	Cause & Fix
INTERNAL_ERROR	500	Unexpected server error. Quote the `request_id` when contacting support.
SERVICE_UNAVAILABLE	503	Platform maintenance window. Retry with exponential backoff.