Bookivox Documentation

Format général

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

{ "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 :

{
  "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."
    }
  }
}

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 :

Relisez la session : GET /workflow/{workflow_id}/text-chat/sessions/{run_id}.
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

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

En-têtes et wrapper.

Endpoints

Le cheatsheet complet.

Last modified on October 28, 2026

Agents

Base de connaissance

Campagnes

Chat texte

Clés API

Crédits et usage

Node-types

Outils

Téléphonie

Templates

Erreurs

Format général

Exemples réels par code

Erreurs du catalogue

Conflits `409`

Stratégie de retry

Vérifier votre plan d’action

Démarrage rapide

Endpoints

​Format général

​Exemples réels par code

​Erreurs du catalogue

​Conflits 409

​Stratégie de retry

​Vérifier votre plan d’action

Démarrage rapide

Endpoints

Format général

Exemples réels par code

Erreurs du catalogue

Conflits `409`

Stratégie de retry

Vérifier votre plan d’action