Cette page liste les erreurs que vous pouvez recevoir, leur signification et quoi faire. Les erreurs REST sont des corps JSON {"error": "<code>"} avec un statut HTTP ; l’API Erlang renvoie {error, Reason}. Utilisez-la quand un appel échoue et que vous cherchez la correction, pas la cause ; Dépannage part au contraire du symptôme.
La forme des erreurs REST
{"error": "conflict"}
Certains codes ajoutent des champs : reason (un corps /find invalide, des att_opts invalides), message, line et column (une erreur de syntaxe BQL), current (un conflit de pièce jointe), tokens (missing_bodies).
Remarque
Une erreur que le serveur ne traduit pas devient un 500 avec le terme Erlang imprimé dans la chaîne error, par exemple {"error":"{dimension_mismatch,768,2}"}. C’est pourquoi certains problèmes de configuration répondent 500 plutôt que 4xx.
Authentification
Statut
error
Signification et correction
401
unauthorized
Pas de token, un token faux, inconnu ou révoqué, ou une signature invalide ou rejouée. La réponse porte www-authenticate: Bearer. Envoyez Authorization: Bearer avec un token valide, ou signez à nouveau.
401
signature_v3_required
Une signature v1 ou v2 sur une requête qui porte un en-tête d’écriture ou écrit une pièce jointe. Signez en v3.
401
content_hash_mismatch
Le corps ne correspond pas à son hash signé dans x-barrel-content-sha256. Calculez le hash des octets exacts que vous envoyez.
400
bad_body
Le corps d’une requête signée n’a pas pu être lu. Réessayez.
403
forbidden
Le jeton de capacité n’a pas le droit, est pour un autre espace, ou la route n’accepte qu’un token serveur.
413
too_large
Un corps signé au-delà de max_body (1 Gio par défaut).
Bases et documents
Statut
error
Signification et correction
400
invalid_name
Le nom ne suit pas la règle : utilisez des lettres minuscules, des chiffres, _ et -, de 1 à 63 octets, sans _ en premier. Avant la 1.14.0, barrel_server répondait 500 invalid_db_name aux noms en majuscules.
404
db_not_found
La base n’existe pas. Seul PUT /db/:db (ou l’outil MCP db_create) en crée une ; créez-la d’abord.
400
bad_att_opts + reason
Des att_opts invalides dans le corps de PUT /db/:db.
404
not_found
Le document, la version ou la pièce jointe n’existe pas.
409
conflict
Le _rev envoyé n’est pas le courant. Relisez et réessayez avec le nouveau _rev.
400
bad_json
Le corps n’est pas du JSON.
400
invalid_provenance
Un en-tête x-barrel-actor, x-barrel-session ou x-barrel-source est trop long (256 octets chacun, 1 Kio ensemble).
400
bad_since, bad_until, bad_limit
Un paramètre de requête invalide sur GET /db/:db/_history.
GET /db/:db/changes avec un since invalide n’échoue pas : il repart du premier changement.
Requêtes
Statut
error
Signification et correction
400
invalid_query + message, line, column
Erreur de syntaxe BQL. BQL n’a ni COUNT ni GROUP BY.
400
invalid_query + reason
Une clé inconnue dans un corps /find, ou une continuation mal formée. Renvoyez la continuation de meta telle quelle.
400
missing_query
Un corps JSON sans query.
400
invalid_max_rows, invalid_deadline_ms
Pas un entier positif (1000 lignes au plus, 300000 ms).
400
subscribe_requires_sse
Une instruction SUBSCRIBE sans Accept: text/event-stream ni ?feed=sse.
dans le flux
deadline
L’échéance est passée après l’envoi de quelques lignes ; la dernière ligne NDJSON est {"error":"deadline"}.
Recherche
Ce sont des problèmes de configuration, mais ils répondent 500.
Statut
error
Signification et correction
500
bm25_not_enabled
La recherche par mots-clés est désactivée sur cette base. Ouvrez-la avec vectordb => #{bm25_backend => disk}, ou utilisez le mode enregistrement.
500
embedder_not_configured
Aucun embedder pour transformer votre texte en vecteur. Configurez-en un, ou envoyez un vecteur.
500
{dimension_mismatch,768,N}
Votre vecteur a N dimensions ; le magasin en attend 768.
Pièces jointes
Statut
error
Signification et correction
409
conflict + current
Une condition If-Match ou If-None-Match: * a échoué.
400
bad_if_none_match
Seul * est accepté dans If-None-Match.
501
attachments_disabled
La base a été créée avec att_opts => #{backend => none}.
501
conditional_writes_unsupported
Le backend S3 ne sait pas faire d’écritures conditionnelles (Garage).
503
att_sync_pending
Une nouvelle branche adossée à S3 est encore en cours de copie. Réessayez un peu plus tard.
Branches
Statut
error
Signification et correction
400
invalid_name
Un nom de branche invalide.
400
bad_at
at n’est pas un curseur du flux de changements, ou at_time n’est pas en RFC 3339.
400
pitr_window_exceeded
L’instant est plus ancien que l’historique conservé.
409
already_exists
Une branche de ce nom existe.
409
cannot_branch_a_branch
Créez plutôt la branche depuis le parent.
409
not_a_branch
La fusion a été appelée sur une base qui n’est pas une branche.
404
parent_not_found
Le parent de la branche n’est pas ouvert.
Protocole de réplication
Statut
error
Signification et correction
404
not_found
La base n’existe pas ; la réplication n’en crée jamais.
Un membre en échec est signalé dans sources[] de la réponse, pas comme une erreur de requête.
MCP
Une requête sans token sur un serveur verrouillé reçoit un HTTP 401. Les erreurs d’outil reviennent comme résultat d’outil avec isError: true et le même corps JSON, par exemple {"error":"not_found"} ou {"error":"forbidden","db":"kb"}.
API Erlang
Cycle de vie et documents
Retour
Signification et correction
{error, already_exists}
create_db sur une base ouverte. Utilisez open_db/1.
{error, invalid_db_name}
Lettres minuscules, chiffres, _ et -, de 1 à 63 octets. Un _ en premier est réservé aux bases propres à barrel.
{error, not_found}
Un document absent, ou une base qui ne tourne pas.
{error, {db_failed, Reason}}
L’écrivain de la base a planté 3 fois en 60 secondes. Corrigez Reason, puis reopen_db/1.
{error, conflict}
Un _rev périmé.
{error, read_only}
Une écriture sur une base ouverte avec read_only => true.
{error, clock_skew}
L’horloge est en retard sur l’écriture la plus récente de la base, ou un HLC distant a été refusé. Corrigez l’horloge.
{error, {invalid_expires_at, V}}
expires_at doit être un temps unix positif ou nul en millisecondes.
{error, {invalid_provenance, _}}
Champs de provenance trop longs.
{error, {invalid_condition, C}}
Une condition find invalide.
{error, db_restarted}
Un flux ou un envoi de pièce jointe a survécu à un redémarrage de la base. Rouvrez-le ; l’envoi n’a rien publié.
{error, upload_expired}
Un envoi laissé ouvert plus longtemps que att_upload_timeout (3600 s).
{error, {read_only_upgrade_needed, _}}
Des magasins qui demandent une mise à niveau, ouverts en lecture seule. Ouvrez une fois en écriture.
BQL
Retour
Signification et correction
{error, {parse_error, {Line, Col}, Msg}}
Une erreur de syntaxe, depuis barrel_docdb:query/2,3.
{error, {invalid_query, {Line, Col}, Code}}
Une instruction que la grammaire accepte mais que le compilateur refuse. Voir BQL.
{error, {table_fn_requires_barrel, Fn}}
Les fonctions de table de recherche ne s’exécutent que via barrel:query/2,3.
{error, {unsupported, subscribe}}
SUBSCRIBE via query ; utilisez subscribe_query/2,3.
{error, {limit_required, #{max_limit := 1000}}}
Une requête de contexte sans LIMIT.
Module barrel
Retour
Signification et correction
{error, no_vector_store}
Un appel vectoriel, ou un export, sur une base ouverte avec vectordb => none.
{error, record_mode}
vector_add sur une base en mode enregistrement ; écrivez plutôt le document.
{error, mixed_batch}
Une liste vector_add_batch/2 qui mélange des entrées avec et sans vecteurs.
{error, {invalid_option, vectordb}}
embedding avec vectordb => none.
{error, no_stored_policy}
embedding => stored sur une base qui n’a jamais tourné en mode enregistrement.
{error, barrel_app_not_started}
Le mode enregistrement demande que l’application barrel soit démarrée.
{error, {unknown_options, Keys}}
Des clés inconnues dans une politique d’embedding.
{error, {dimension_mismatch, Want, Got}}
Un vecteur de mauvaise longueur.
{error, {index_init_failed, faiss_not_available}}
backend => faiss sans le NIF barrel_faiss.
Chiffrement
Retour
Signification et correction
{error, db_is_encrypted}
Passez la spécification de chiffrement à l’ouverture.
{error, wrong_encryption_key}
La clé ne correspond pas à cette base.
{error, cannot_encrypt_existing_db}
Pas de chiffrement sur place. Créez une base chiffrée et répliquez-y les données.