Développeurs

Gestion des erreurs

Chaque erreur de l'API publique (API banque comprise) est un document RFC 9457 application/problem+json portant un code stable. Le lien type d'une erreur pointe vers la section de cette page qui la décrit : https://docs.tauraco.ai/developers/erreurs#<code>.

{"type":"https://docs.tauraco.ai/developers/erreurs#insufficient_scope","title":"Scope insuffisant",
 "status":403,"detail":"Le jeton ne porte pas invoices:read.","instance":"/public/v1/invoices",
 "code":"insufficient_scope","request_id":"5b0c2a1e-8f3d-4c55-9a51-0d7e6f1b2c3d",
 "required_scopes":["invoices:read"]}

code : la valeur à tester dans votre programme (liste fermée ci-dessous) ; title et detail sont des textes pour un humain et peuvent changer.
request_id : identique à l'en-tête X-Request-Id ; citez-le au support.
Champs facultatifs : errors (422 : [{field, message}]), retry_after (429), required_scopes (403).
Une erreur interne ne renvoie jamais de détail technique.

Les points /oauth/* suivent le format OAuth ({"error", "error_description"}, voir Authentification) ; le serveur MCP répond par des codes HTTP au niveau du transport et par isError dans un outil (voir Documentation MCP).

Que réessayer

Statut	Réessayer ?
400, 401, 403, 404, 405, 410, 413, 415, 422	non : corriger la requête, le jeton ou les droits
409	selon le code : `idempotency_in_progress` et `export_not_ready` après un délai ; `conflict` après relecture de l'état
429	oui, après `Retry-After`
500, 502, 503	oui, avec attente exponentielle et la même `Idempotency-Key` pour un `POST`

invalid_request

400. Requête mal formée : en-tête invalide, paramètre inconnu pour l'opération, JSON illisible. Corrigez la requête ; errors désigne le paramètre fautif quand c'est possible.

invalid_cursor

400. Curseur illisible, expiré, signé pour un autre jeu de données ou avec d'autres filtres. Repartez de la première page avec les mêmes filtres.

idempotency_key_required

400. POST sans en-tête Idempotency-Key. Générez une clé unique (UUID v4) par opération métier et conservez-la pour les reprises.

unauthenticated

401. Jeton absent, illisible, expiré, d'une autre audience ou d'un autre émetteur ; WWW-Authenticate: Bearer error="invalid_token". Demandez un nouveau jeton.

grant_revoked

401. L'application est suspendue, l'octroi est révoqué ou expiré, ou l'utilisateur délégant a perdu son rôle ou son compte. Un nouveau jeton ne suffit pas : l'entreprise doit autoriser à nouveau l'application.

insufficient_scope

403. Le jeton ne porte pas le scope exigé ; required_scopes et WWW-Authenticate … scope="…" le nomment. Demandez le scope (l'administrateur doit l'avoir accordé dans l'octroi).

forbidden

403. Le scope est présent mais une règle métier refuse : rôle de l'utilisateur, habilitation de l'établissement, régime de l'entreprise, données personnelles réservées. Ne réessayez pas sans changement de droits.

not_found

404. Ressource absente ou non visible pour votre octroi (une ressource d'une autre entreprise donne la même réponse) ; aussi un module fermé.

method_not_allowed

405. Méthode HTTP non prise en charge sur ce chemin.

conflict

409. L'état de la ressource ne permet pas l'opération (transition refusée par le service, identité de l'entreprise incomplète). Relisez la ressource avant de décider.

idempotency_in_progress

409. Une requête avec la même Idempotency-Key est en cours de traitement. Réessayez après quelques secondes avec la même clé.

export_not_ready

409. L'export n'est pas encore SUCCEEDED. Interrogez son état ou attendez l'événement export.completed.

regime_not_supported

409. Format ou jeu indisponible pour le régime comptable de l'entreprise (par exemple le FEC hors plan comptable français).

export_expired

410. Le fichier a été purgé (30 jours) ou supprimé. Relancez l'export.

payload_too_large

413. Corps supérieur à 1 Mo (API) ou 4 Mo (MCP).

unsupported_media_type

415. Content-Type autre que application/json sur une écriture.

validation_failed

422. Corps ou filtres invalides ; errors: [{field, message}] détaille chaque champ.

idempotency_key_reused

422. La même Idempotency-Key a déjà servi avec un corps différent. Utilisez une nouvelle clé pour une nouvelle opération.

export_limit_exceeded

422. Plafond de l'export dépassé (lignes, octets, durée, ou 5 000 lignes en PDF). Réduisez la période ou les colonnes, ou découpez l'export.

rate_limited

429. Seau par minute de l'application vide. Attendez Retry-After secondes ; X-Quota-Remaining n'est pas renvoyé sur ce refus.

quota_exceeded

429. Quota journalier atteint ; Retry-After court jusqu'à minuit UTC.

upstream_unavailable

502. Service distant en échec : relais des marchés publics ou logiciel cible d'un connecteur. Réessayez plus tard.

service_unavailable

503. Dépendance indisponible (service de débit, stockage, chaîne de données cloisonnée du financement). Réessayez après Retry-After.

internal_error

500. Erreur inattendue ; aucun détail n'est renvoyé. Réessayez une fois, puis écrivez au support avec le request_id.