Errors

Relay uses conventional HTTP status codes and returns a consistent JSON error envelope so you can handle failures programmatically.

Error envelope

Every error response has a single error object with a machine-readable type, a code (mirrors type by default), and a human-readable message:

Error response

{
  "error": {
    "type": "validation_error",
    "code": "validation_error",
    "message": "identity has invalid characters"
  }
}

Common error types

Type	Status	Description
`unauthorized`	401	The API key is missing or invalid.
`key_revoked`	401	The API key was valid but has been revoked.
`forbidden`	403	The key is valid but not permitted to perform this action.
`not_found`	404	The requested resource does not exist.
`invalid_request`	400 / 422	The request was malformed — for example a body that is not valid JSON, or a request that could not be fulfilled.
`validation_error`	422	The request body failed schema validation.
`rate_limited`	429	The API key exceeded its rate limit. Inspect the RateLimit-* headers and retry after the Retry-After delay.
`quota_exceeded`	402	The organization's monthly participant-minute quota for its plan has been reached. Returned by POST /v1/tokens and POST /v1/rooms.