Error Codes

This catalogue lists the identifiers, HTTP statuses, and remediation guidance shared across the REST API and SDK layers.

Error payload structure (REST)

Most HTTP endpoints return the same envelope for error responses:


{
  "error": {
    "message": "Invalid ephemeral token",
    "type": "invalid_request_error",
    "param": null,
    "code": null
  }
}

Field definitions:

Field	Description
`message`	Human-readable summary (can be surfaced directly to logs/UI).
`type`	Machine-readable category such as `invalid_request_error` or `not_found_error`.
`param`	Populated when a specific field is invalid.
`code`	Reserved for sub-codes (currently unused).

Validation errors (HTTP 422) follow the standard FastAPI detail array with loc, msg, and type keys.

Identifier	HTTP status	Surface	Description	Recommended action
`invalid_request_error`	400 / 401	REST (`/v1/realtime/client-secrets`, `/v1/realtime/ice-config`, `/v1/realtime/calls`)	Request is malformed or the bearer token is invalid/expired.	Regenerate an ephemeral token via `client-secrets` and retry.
`not_found_error`	404	REST	Resource not found or endpoint not recognized.	Verify the endpoint URL and check that the requested resource exists.
`missing` (validation)	422	REST	Required field absent in the query/body.	Supply the missing field (e.g., `offer`, `params`).
`invalid_ephemeral_token`	401	REST (`ice-config`, `calls`)	Ephemeral token expired or already consumed.	Fetch a new token for each session; tokens are single-use.
`OrgaAIAuthenticationError`	401 / 403	Node SDK (`@orga-ai/node`)	Permanent API key is invalid or missing.	Verify that `ORGA_API_KEY` is correctly set in your environment variables.
`OrgaAIServerError`	5xx / network timeout	Node SDK	Upstream Orga Cloud responded with an error or timed out.	Retry with exponential backoff; inspect `error.status` and enable `debug: true`.
`timeout_error`	Client-side (no HTTP response)	Node SDK	SDK timed out waiting for Orga Cloud.	Increase `timeout` in `OrgaAIConfig` or ensure outbound HTTPS is allowed.

Client SDKs expose error states via useOrgaAI()—when the REST API returns invalid_request_error, it propagates as a rejected startSession() promise with the same message.
The Node SDK wraps HTTP failures in OrgaAIAuthenticationError or OrgaAIServerError. Check the instanceof chain to apply custom logging (see server errors).

Log the type, HTTP status, and correlation IDs—not the ephemeral token or API key.
Downgrade expected validation errors (422) to warnings so that alerting systems focus on authentication/network failures.
When debugging WebRTC connection issues, enable logLevel: 'debug' in the client SDK to see the underlying error reason returned by /v1/realtime/calls.