# Errors
Source: https://docs.mserve.ai/docs/resources/errors
Summary: OpenAI-shaped routes return the OpenAI error envelope. ElevenLabs-shaped routes return the ElevenLabs one. Stable codes, named parameters.
Availability: available
Last reviewed: 2026-08-25

## OpenAI envelope

```json
{
  "error": {
    "message": "'model' is required.",
    "type": "invalid_request_error",
    "param": "model",
    "code": "missing_required_parameter"
  }
}
```

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `message` | `string` | no |  | Human-readable. Names the problem and, where possible, the recovery. |
| `type` | `"invalid_request_error" | "rate_limit_error" | "insufficient_balance" | "server_error"` | no |  | Client problem, limit, balance, or platform problem. |
| `param` | `string | null` | no |  | The field responsible, when one is. |
| `code` | `string | null` | no |  | Stable machine-readable code. Branch on this. |

## ElevenLabs envelope

ElevenLabs-shaped routes (`/elevenlabs/v1/text-to-speech`, `/elevenlabs/v1/voices`, `/elevenlabs/v1/speech-to-text`, `/elevenlabs/v1/speech-to-speech`, `/elevenlabs/v1/history`) return the ElevenLabs `detail` shape with `422` for validation errors, as the `elevenlabs` SDK expects.

```json
{ "detail": { "status": "unsupported_parameter", "message": "diarize and num_speakers are not supported yet" } }
```

## Codes

| Status | `code`                       | Meaning                                                                          | Recovery                                                                               |
| ------ | ---------------------------- | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| 400    | `unsupported_parameter`      | The field is not supported on this route.                                        | Remove the field named in `param`. See [Compatibility](/docs/resources/compatibility). |
| 400    | `missing_required_parameter` | A required field is absent.                                                      | Add the field named in `param`.                                                        |
| 400    | `invalid_value`              | A value is outside the allowed set, for example `response_format` or `endpoint`. | Use a listed value.                                                                    |
| 401    | `invalid_api_key`            | Missing, wrong, or revoked key.                                                  | Check the header.                                                                      |
| 402    | `insufficient_balance`       | Account balance is zero.                                                         | [Add credits](/docs/resources/billing).                                                |
| 402    | `key_spend_limit_reached`    | This key hit its period ceiling.                                                 | Raise the limit or use another key.                                                    |
| 404    | `model_not_found`            | Unknown model id.                                                                | Use a model id from [Pricing](/docs/pricing).                                          |
| 404    | `voice_not_found`            | Unknown voice id. Never a default voice.                                         | Use a listed voice or alias.                                                           |
| 429    | `rate_limit_exceeded`        | Per-key RPM or concurrency.                                                      | Wait `Retry-After`.                                                                    |
| 502    | `upstream_error`             | The model did not answer. Nothing billed.                                        | Retry with backoff.                                                                    |
| 503    | `model_booting`              | The model is starting.                                                           | Wait `Retry-After`.                                                                    |
| 503    | `no_capacity`                | No capacity for the model right now.                                             | Retry with backoff.                                                                    |

## Model errors

Errors raised by the model come back in the same envelope with the same status code. An out-of-range `temperature` arrives as a `400` with `param` set to `temperature`.

## Handling errors in the SDK

**Python**

```python
import openai

try:
    client.chat.completions.create(model="qwen3.8-27b", messages=msgs, audio={"voice": "alloy"})
except openai.BadRequestError as e:
    print(e.body["code"], e.body["param"])  # unsupported_parameter audio
except openai.RateLimitError as e:
    retry_after = int(e.response.headers.get("retry-after", "5"))
except openai.APIStatusError as e:
    if e.status_code == 402:
        print("add credits")
```

**JavaScript**

```ts
import OpenAI from "openai";

try {
  await client.chat.completions.create({ model: "qwen3.8-27b", messages, audio: { voice: "alloy" } });
} catch (e) {
  if (e instanceof OpenAI.BadRequestError) console.log(e.error.code, e.error.param); // unsupported_parameter audio
  if (e instanceof OpenAI.RateLimitError) console.log(e.headers?.["retry-after"]);
  if (e instanceof OpenAI.APIError && e.status === 402) console.log("add credits");
}
```