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

# Errors

> Error codes with HTTP status, domain, and retry guidance.

Every error response includes `ok: false` and a machine-readable `code`.

## Error envelope

```json theme={null}
{
  "ok": false,
  "code": "AUTH_REQUIRED",
  "detail": "Authentication required.",
  "error": "Authentication required."
}
```

## Reference

| Code                                       | Status | Domain     | Retry? | Default message                                                            |
| ------------------------------------------ | -----: | ---------- | ------ | -------------------------------------------------------------------------- |
| `BAD_REQUEST`                              |    400 | common     | No     | The request is invalid.                                                    |
| `AUTH_INVALID_SESSION`                     |    401 | auth       | No     | Invalid session.                                                           |
| `AUTH_REQUIRED`                            |    401 | auth       | No     | Authentication required.                                                   |
| `AUTH_SESSION_EXPIRED`                     |    401 | auth       | No     | Session expired.                                                           |
| `AUTH_USER_UNAVAILABLE`                    |    401 | auth       | No     | User not available.                                                        |
| `BILLING_INSUFFICIENT_CREDITS`             |    402 | billing    | No     | Insufficient credits.                                                      |
| `AUTH_ADMIN_ACCESS_DENIED`                 |    403 | auth       | No     | Admin console access denied.                                               |
| `AUTH_ADMIN_ROLE_REQUIRED`                 |    403 | auth       | No     | Admin role required.                                                       |
| `FORBIDDEN`                                |    403 | common     | No     | Forbidden.                                                                 |
| `RESOURCE_NOT_FOUND`                       |    404 | common     | No     | Resource not found.                                                        |
| `CONFLICT`                                 |    409 | common     | No     | The request conflicts with current state.                                  |
| `STUDIO_AUDIO_EXPORT_BLOCKED`              |    409 | studio     | No     | Studio audio export is blocked by missing or stale clips.                  |
| `STUDIO_AUDIO_EXPORT_INCOMPATIBLE_AUDIO`   |    422 | studio     | No     | Studio audio export requires compatible PCM WAV clip audio.                |
| `STUDIO_AUDIO_EXPORT_NO_AUDIO`             |    422 | studio     | No     | Studio audio export has no clip audio to export.                           |
| `STUDIO_AUDIO_EXPORT_UNSUPPORTED_SOURCE`   |    422 | studio     | No     | Studio audio export requires supported clip audio sources.                 |
| `VALIDATION_ERROR`                         |    422 | common     | No     | Request validation failed.                                                 |
| `GENERATION_NOT_READY`                     |    425 | generation | Yes    | Generation is not ready yet.                                               |
| `GENERATION_CONCURRENCY_EXCEEDED`          |    429 | generation | Yes    | Your plan's concurrent generation limit was reached. Please retry shortly. |
| `RATE_LIMITED`                             |    429 | common     | Yes    | Rate limit exceeded.                                                       |
| `INTERNAL_ERROR`                           |    500 | common     | Yes    | Internal server error.                                                     |
| `STUDIO_AUDIO_EXPORT_FAILED`               |    500 | studio     | Yes    | Studio audio export failed.                                                |
| `GENERATION_FAILED`                        |    502 | generation | Yes    | Generation failed.                                                         |
| `GENERATION_INVALID_RESPONSE`              |    502 | generation | Yes    | Generation service returned an invalid response.                           |
| `UPSTREAM_ANALYTICS_ERROR`                 |    502 | upstream   | Yes    | Analytics service request failed.                                          |
| `UPSTREAM_BILLING_ERROR`                   |    502 | upstream   | Yes    | Billing service request failed.                                            |
| `UPSTREAM_GENERATION_ERROR`                |    502 | upstream   | Yes    | Generation service request failed.                                         |
| `UPSTREAM_GENERATION_SERVICE_ERROR`        |    502 | upstream   | No     | Generation service request failed.                                         |
| `VOICE_CLONE_FAILED`                       |    502 | voice      | Yes    | Voice clone failed.                                                        |
| `VOICE_DESIGN_FAILED`                      |    502 | voice      | Yes    | Voice design failed.                                                       |
| `AUTH_CONFIG_MISSING`                      |    503 | auth       | No     | Authentication is not configured correctly.                                |
| `DISPATCH_TIMEOUT`                         |    503 | generation | Yes    | Generation dispatch timed out before execution. Please try again.          |
| `GENERATION_CAPACITY_EXCEEDED`             |    503 | generation | No     | Generation capacity is currently exhausted. Please try again shortly.      |
| `GENERATION_INTERRUPTED`                   |    503 | generation | Yes    | Generation was interrupted by a service restart. Please try again.         |
| `LLM_CONFIG_NOT_FOUND`                     |    503 | upstream   | No     | LLM feature is not configured.                                             |
| `STUDIO_AUDIO_EXPORT_ASSET_READ_FAILED`    |    503 | studio     | Yes    | Studio audio export could not read clip audio from storage.                |
| `STUDIO_AUDIO_EXPORT_ASSET_WRITE_FAILED`   |    503 | studio     | Yes    | Studio audio export could not write the result to storage.                 |
| `STUDIO_AUDIO_EXPORT_STORAGE_UNCONFIGURED` |    503 | studio     | No     | Studio audio export storage is not configured.                             |
| `UPSTREAM_ASSET_STORAGE_ERROR`             |    503 | upstream   | Yes    | Audio asset storage failed.                                                |
| `GENERATION_TIMEOUT`                       |    504 | generation | Yes    | Generation timed out. Please try again.                                    |
| `UPSTREAM_TIMEOUT`                         |    504 | upstream   | Yes    | Upstream request timed out.                                                |

## Operational guidance

<Columns cols={2}>
  <Card title="Authentication" icon="key-round" href="/authentication">
    Send API keys correctly and distinguish session-only account endpoints from API-key endpoints.
  </Card>

  <Card title="Rate limits" icon="gauge" href="/reference/rate-limits">
    Retry concurrency, capacity, and timeout errors without overloading generation.
  </Card>

  <Card title="CLI troubleshooting" icon="wrench" href="/cli/reference/troubleshooting">
    Map CLI exit codes to auth, quota, timeout, network, and dependency fixes.
  </Card>

  <Card title="Developer logs" icon="activity" href="https://breezeblue.ai/app/developer/logs">
    Inspect failed requests, latency, request IDs, and generated cURL examples.
  </Card>
</Columns>