Lire les erreurs

Les erreurs reviennent en application/problem+json, dans l’esprit de la RFC 7807. type est une URI d’identifiant stable, et chacune a sa page d’explication sur https://docs.d2b.dev/errors/<slug>.

{
  "type": "https://docs.d2b.dev/errors/validation",
  "title": "Transform validation failed",
  "detail": "Avoid hard-coding source names in the template …",
  "status": 400,
  "trace_id": "8f3c…",
  "suggested_fix": "Use {{ arg }} placeholders and bind via `args`. See /api/v1/workbooks/{cid}/artifacts to discover names.",
  "alternative_tools": ["get_lineage"]
}

suggested_fix est rédigé comme une phrase qu’un LLM peut lire telle quelle pour décider de sa prochaine action — le pattern recommandé est de passer le message d’exception entier dans la boucle de l’agent. Le SDK lève des exceptions avec le suggested_fix, et la CLI écrit la même phrase sur stderr.

type	Status typique	Signification
validation	400 / 422	L’entrée ne respecte pas le contrat (échec SQL, nom interdit, référence codée en dur dans un template, etc.)
propagation-failed	400	La transformation a été enregistrée et matérialisée ; la reconstruction d’une transformation en aval a ensuite échoué
unauthorized	401	PAT absent, invalide ou révoqué
forbidden	403	Scope insuffisant, refus par une politique (mask / deny), hors du scope workbook
unknown-workbook	404	Le workbook n’existe pas ou n’est pas visible
unknown-artifact	404	La table ou l’artifact n’existe pas, ou son type n’est pas exposé sur /api/v1
conflict	409	Verrouillage optimiste (expected_version décalé), workbook en cours de traitement, nom en double
rate-limited	429	Limite de débit. Respectez Retry-After
internal	5xx	Échec côté serveur. Contactez-nous en joignant le trace_id

5xx et trace_id

Les réponses 5xx utilisent la même enveloppe problem+json. Le trace_id (aussi dans l’en-tête X-D2B-Trace-Id) correspond 1:1 à la stack trace côté serveur — joignez-le à tout signalement. Les jobs d’ingest asynchrone en échec portent aussi trace_id et la phase fautive (phase).

Pour les surfaces où le vocabulaire REST (GET /api/...) ne convient pas, les erreurs concernées incluent aussi suggested_fix_cli (vocabulaire d2b ...). La CLI affiche cette variante automatiquement.