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

# Errors & response envelope

> The standard JSON envelope and HTTP status codes used by the Voice API.

## Response envelope

JSON endpoints return a consistent envelope with a boolean `error` flag. On success, `error` is
`false` and the payload is in `data`:

```json theme={null}
{
  "status": 200,
  "data": { "...": "endpoint payload" },
  "error": false
}
```

On failure, `error` is `true`, `data` is omitted, and `message` carries the detail:

```json theme={null}
{
  "status": 422,
  "error": true,
  "message": "audio_too_short"
}
```

<Note>
  The audio endpoints don't use this envelope on success: [`/speak`](/voice-api/synthesize-speech)
  returns raw audio bytes and [`/stream`](/voice-api/stream-speech) returns a Server-Sent Events body.
  Errors on those endpoints still return the JSON envelope above.
</Note>

### Plan-limit & entitlement denials

Billing-related denials do **not** use the standard envelope - they return a flat JSON body.

Per-resource plan limits (for example creating more voices than your plan allows) return `403`:

```json theme={null}
{
  "error": "plan limit reached",
  "feature": "max_voices",
  "limit": 10
}
```

When metered-usage enforcement is active, an exhausted allowance returns `402`, and a feature your
plan doesn't include returns `403`. Both carry the unit and the current usage:

```json theme={null}
{
  "error": "quota_exhausted",
  "unit": "character",
  "limit": 100000,
  "used": 100000
}
```

The `error` string is the denial reason (e.g. `quota_exhausted`, `insufficient_credits`,
`limit_reached`, or `feature_disabled`).

## Status codes

| Status | When it happens |
| - | - |
| `200` | Success (GET, and the audio/stream endpoints). |
| `201` | Resource created. |
| `202` | Accepted - asynchronous enroll/clone job started. |
| `400` | Invalid request - missing/invalid field, text too long (> 10,000 chars), or the voice isn't ready yet. |
| `401` | Missing or invalid `X-API-Key`. |
| `402` | Metered allowance exhausted (billing enforcement) - see plan-limit denials above. |
| `403` | Not permitted, a plan limit was reached, or a feature is disabled for your plan. |
| `404` | Voice or resource not found - including voices owned by another workspace. |
| `422` | The voice provider rejected the input (for example, a reference clip that's too short). |
| `429` | Rate limited - retry after a short delay. |
| `502` | The voice provider is temporarily unavailable. |

## Common messages

<AccordionGroup>
  <Accordion title="Voice is not enrolled yet">
    The voice you referenced isn't ready to use - only voices with status `ready` can synthesize. See
    [Working with voices](/concepts/voices).
  </Accordion>

  <Accordion title="text too long (max 10000 chars)">
    The `text` field exceeds the 10,000-character limit. Split long input into multiple requests.
  </Accordion>

  <Accordion title="Provider errors (422 / 429 / 502)">
    These originate from the upstream synthesis provider. `422` is a validation issue with your input,
    `429` is rate limiting, and `502` means the provider is warming up or unavailable - retry with
    backoff.
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.