Errors and Rate Limiting

Error response format

All error responses use a compact JSON format:

{
  "error": "Human-readable error message",
  "code": "MACHINE_READABLE_CODE",
  "suggestion": "A safe next action",
  "docs": "https://docs.omnilux.tv/errors/MACHINE_READABLE_CODE",
  "requestId": "<request-id>"
}

Field	Type	Description
error	string	Human-readable error description
code	string	Machine-readable error code
details	object	Optional structured context
suggestion	string	Optional safe next action
docs	string	Canonical documentation for the code
requestId	string	Optional request identifier that also appears in X-Request-Id

HTTP status codes

Status	Meaning
400	Bad request
401	Missing or invalid authentication
403	Authenticated but not permitted
404	Resource not found
409	Request conflicts with current state
429	Request rate limited
500	Internal server error

Common error codes

Code	Typical meaning
AUTH_MISSING_TOKEN	The request did not include an Authorization: Bearer <token> header
AUTH_INVALID_CREDENTIALS	Wrong username or password
AUTH_SESSION_EXPIRED	Session token has expired
AUTH_INSUFFICIENT_ROLE	The signed-in user lacks the required role
MEDIA_NOT_FOUND	Requested media was not found
RATE_LIMIT_EXCEEDED	Too many requests
STREAM_TRANSCODE_FAILED	The server could not prepare the stream

Rate limiting

OmniLux rate-limits API requests to protect the server. Exact thresholds and behavior can vary by endpoint and server configuration, so clients should always handle 429 responses gracefully and retry later.