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

# Erreurs

> Formats d'erreur de l'API Bookivox, exemples réels par code, erreurs du catalogue et stratégie de retry.

## Format général

La plupart des erreurs renvoient un objet JSON avec une seule clé `detail` :

```json theme={null}
{ "detail": "..." }
```

`detail` peut être une **chaîne** (cas simple) ou un **objet structuré**
(validation `422`, erreurs du catalogue, conflits).

## Exemples réels par code

| Code | `detail` typique |
| - | - |
| `401` | `X-API-Key header required` |
| `400` | `Authorization header not allowed` |
| `403` | `Billing write operations are not available via API key` |
| `403` | `Telephony provisioning is not available via API key` |
| `404` | Ressource introuvable |
| `409` | Conflit de révision (text-chat) |
| `422` | Erreurs Pydantic (champs manquants/invalides) |

## Erreurs du catalogue

Certaines erreurs métier (knowledge base, quota…) renvoient un `detail` objet
avec des **messages localisés** (`localized_messages`) en **FR** et **EN**.
Exemple de clé de code :

```json theme={null}
{
  "detail": {
    "code": "knowledge_base_upload_url_failed",
    "localized_messages": {
      "fr": "Impossible de générer l'URL d'upload.",
      "en": "Failed to generate upload URL."
    }
  }
}
```

> [!NOTE]
>
> Ces codes sont stables : vous pouvez vous y fier pour afficher un message
> utilisateur propre dans la langue de votre interface.

## Conflits `409`

Sur le **text-chat**, un `409` indique un **conflit de révision** (deux écritures
concurrentes). Réaction attendue :

1. Relisez la session : `GET /workflow/{workflow_id}/text-chat/sessions/{run_id}`.
2. Réémettez la requête avec `expected_revision` à jour.

## Stratégie de retry

| Code | Retenter ? |
| - | - |
| `502` / `503` / `504` | **Oui**, avec backoff exponentiel |
| `401` | Non |
| `402` | Non, créditez d'abord |
| `403` | Non |
| `422` | Non, corrigez le corps |

> [!WARNING]
>
> Ne retentez jamais en boucle un `402` ou un `401` : vous serez bloqué de la
> même manière. Traitez la cause (crédits, clé) avant de réessayer.

## Vérifier votre plan d'action

> **[Démarrage rapide](https://docs.bookivox.com/api-reference/quickstart)**
>
> En-têtes et wrapper.

> **[Endpoints](https://docs.bookivox.com/api-reference/endpoints)**
>
> Le cheatsheet complet.


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