Errors and failure semantics

Error response

API errors include a machine-readable code, a message, and a request ID. Keep the request ID for troubleshooting, without logging API keys or room tokens.

{
  "error": {
    "code": "invalid_request",
    "message": "Request validation failed"
  },
  "request_id": "<request UUID>"
}

Common API errors

Code	What to check
`invalid_json`	The request body must be valid JSON.
`invalid_request`	Check required fields, field types, and UUIDs.
`idempotency_key_required`	Supply an `Idempotency-Key` of 8–200 characters for call creation.
`invalid_livekit_url`	Use a secure `wss://` URL on the default port or 443, without embedded credentials or a fragment.
`invalid_token_grants`	Check the bridge token’s room, join/publish/subscribe grants, identity, and validity window.
`invalid_participant_identity`	Supply a nonempty remote participant identity.
`session_expired`	Mint a fresh, valid bridge token.
`not_found`	Check the resource ID and project.
`invalid_state`	The resource cannot perform this operation in its current state.

For authentication failures, verify both your bearer key and X-Chert-Project-Id, including the required read or write scope.

Call failures

A successful API request does not guarantee a completed call. Inspect the call’s status, terminal reason, and recorded events. Check worker readiness, webhook response timing, token validity, and the room’s audio publishers. Avoid retrying an outbound creation with a new idempotency key until you have checked whether the original request created a call.

Get started

Build with BYOR

Reference

Other models

Errors and failure semantics

Error response

Common API errors

Call failures

​Error response

​Common API errors

​Call failures

Error response

Common API errors

Call failures