# Errors

REST errors share one envelope and carry a request ID. On a socket, a problem with one event arrives as an error event, and a session that ends closes the socket with a code.

## The error envelope

Every REST error has the same shape, which the OpenAI SDKs parse:

```json
{"error": {"type": "invalid_request", "code": "unsupported_language",
           "message": "language xx-XX is not supported by nemotron-asr-streaming",
           "param": "session.audio.input.transcription.language",
           "request_id": "req_…", "retry_after_ms": null}}
```

`type` and `code` say what went wrong, `param` names the field at fault, and `retry_after_ms` says how long to wait when a retry can help.

| Status | Type | Codes | What to do |
| --- | --- | --- | --- |
| 400 | `invalid_request` | `invalid_json`, `invalid_parameter`, `unsupported_language`, `unsupported_audio_format` | Fix the field named in `param`. |
| 401 | `authentication` | `missing_api_key`, `invalid_api_key`, `invalid_client_secret` | Check the key, or create a new client secret. |
| 403 | `permission` | `model_not_enabled`, `key_revoked`, `insufficient_credit` | At zero credit, top up; retrying alone will not help. |
| 404 | `not_found` | `unknown_model`, `unknown_session` | Check the model or session ID. |
| 409 | `conflict` | `session_closed` | The session has already ended. |
| 429 | `rate_limit` | `concurrency_limit`, `session_rate_limit` | Wait for `Retry-After`, then retry. |
| 503 | `unavailable` | `model_unavailable`, `capacity_exhausted` | Wait for `Retry-After`, then retry. |
| 500 | `internal` | `internal_error` | Retry, and quote `request_id` if it persists. |

## Request IDs

Every response carries an `X-Wave-Request-Id` header, and every error repeats it as `request_id`. Log it, and quote it when you write to [info@dotwave.ai](mailto:info@dotwave.ai) about a request that failed.

## Retries

- **429 and 503**: Wait for `Retry-After`, then retry with backoff.
- **403 `insufficient_credit`**: Top up first; retrying alone will not help.
- **400**: Fix the field named in `param`; the same request fails again.
- **After a socket closes**: Open a new session and continue with new audio. Do not resend audio from the previous session.

## Errors on a socket

A problem with one event does not end the session. A session that ends closes the socket with a code, which each API lists:

- **Live API**: An `error` event. At the end, `session.closed` gives the reason. See [close codes](https://dotwave.ai/docs/live/websocket/#close-title).
- **Realtime API**: An `error` event, with `error.code` and `error.message`. At the end, `session.end` gives the reason. See [close codes](https://dotwave.ai/docs/realtime/websocket/#close-title).
- **Deepgram-compatible API**: An `Error` message, with its `code` and `description`. See [errors and close codes](https://dotwave.ai/docs/deepgram/messages/#errors-title).