> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trychert.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors and failure semantics

> Diagnose invalid requests, credentials, and failed calls.

## 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.

```json theme={null}
{
  "error": {
    "code": "invalid_request",
    "message": "Request validation failed"
  },
  "request_id": "<request UUID>"
}
```

<a id="error-codes" />

## 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.