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

# Errors

Failed requests return an OpenAI-style envelope.

```json theme={null}
{
  "error": {
    "message": "Incorrect API key provided.",
    "type": "invalid_request_error",
    "code": "invalid_api_key",
    "param": null
  }
}
```

A WebSocket that fails to open receives the same envelope as the body of a plain HTTP response, before any frame.

## Authentication

Every request needs `Authorization: Bearer sk_hopper_...`. A missing, incorrect, or disabled key returns 401.

## Credits

A key whose balance has reached zero returns 402 `insufficient_quota`. A streaming transcription session that reaches zero closes with code 1008.

## Rate limits

Each key is limited to 2,000 requests per minute. Over that, the API returns 429 `rate_limit_exceeded` with `Retry-After` in seconds. Text to speech and voice cloning also return 429 when the model is at capacity.

## Codes

| Status | Code                       | Meaning                                                                         |
| ------ | -------------------------- | ------------------------------------------------------------------------------- |
| 400    | `invalid_json`             | Body is not a JSON object                                                       |
| 400    | `invalid_content_type`     | Transcription body is not `multipart/form-data`                                 |
| 400    | `missing_file`             | Transcription request has no `file`                                             |
| 400    | `missing_model`            | Transcription request has no `model`                                            |
| 400    | `missing_name`             | Clone request has no `name`                                                     |
| 400    | `missing_clip`             | Clone request does not carry exactly one clip                                   |
| 400    | `unsupported_audio_format` | Uploaded audio is mp3, ogg, flac, or mp4/m4a                                    |
| 400    | `invalid_sample_rate`      | `sample_rate` is not one the model accepts                                      |
| 400    | `invalid_turn_detection`   | `turn_detection` is not `balanced`, `patient`, or `responsive`                  |
| 400    | `invalid_transcript`       | `input` is empty or not a string                                                |
| 400    | `transcript_too_long`      | `input` is over 1000 characters                                                 |
| 400    | `invalid_output_format`    | `response_format` is not `wav` or `pcm`                                         |
| 400    | `unsupported_parameter`    | Request sets a generation parameter the model does not support, such as `speed` |
| 400    | `invalid_clip`             | Reference clip is rejected by the cloning model                                 |
| 400    | `invalid_scope`            | `scope` is not `featured`, `all`, or `mine`                                     |
| 400    | `invalid_limit`            | `limit` is not an integer between 1 and 200                                     |
| 401    | `invalid_api_key`          | Key is missing or incorrect                                                     |
| 401    | `api_key_disabled`         | Key was disabled in the console                                                 |
| 402    | `insufficient_quota`       | Balance is zero                                                                 |
| 403    | `voice_read_only`          | Voice belongs to the Hopper library, not your organization                      |
| 404    | `model_not_found`          | Model id is not in the catalog                                                  |
| 404    | `voice_not_found`          | No voice with that id                                                           |
| 405    | `method_not_allowed`       | Method is not supported on this path                                            |
| 413    | `body_too_large`           | Body is over 10 MB, or over 25 MB for transcriptions                            |
| 429    | `rate_limit_exceeded`      | Key is over 2,000 requests per minute, or the model is at capacity              |
| 502    | `upstream_unavailable`     | Model server is unreachable                                                     |
| 502    | `upstream_error`           | Model server returned an error                                                  |
| 503    | `model_offline`            | Model has no healthy server right now                                           |
| 503    | `verify_unavailable`       | Key verification is temporarily unavailable                                     |
| 504    | `upstream_timeout`         | Model server did not respond in time                                            |