Fehler lesen

Fehler kommen als application/problem+json im Stil von RFC 7807 zurück. type ist eine stabile Identifier-URI, und zu jeder gibt es eine Erklärungsseite unter 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 ist als Satz formuliert, den ein LLM direkt lesen und daraus die nächste Aktion ableiten kann — das empfohlene Muster ist, die Exception-Message komplett in den Agenten-Loop zu geben. Das SDK wirft Exceptions inklusive suggested_fix, die CLI gibt denselben Text auf stderr aus.

type	Typischer status	Bedeutung
validation	400 / 422	Die Eingabe verletzt den Vertrag (fehlgeschlagenes SQL, unzulässige Namen, hartcodierte Referenzen im Template usw.)
propagation-failed	400	Die Transformation wurde gespeichert und materialisiert; anschließend schlug der Neuaufbau einer nachgelagerten Transformation fehl
unauthorized	401	PAT fehlt, ist ungültig oder widerrufen
forbidden	403	Fehlender Scope, Ablehnung durch Policy (mask / deny), außerhalb des Workbook-Scopes
unknown-workbook	404	Workbook existiert nicht oder ist nicht sichtbar
unknown-artifact	404	Tabelle / Artifact existiert nicht oder hat einen Typ, der nicht unter `/api/v1` exponiert ist
conflict	409	Optimistisches Locking (`expected_version` weicht ab), Workbook ist gerade in Verarbeitung, Namensduplikat
rate-limited	429	Rate-Limit erreicht. `Retry-After` befolgen
internal	5xx	Serverseitiger Fehler. Mit `trace_id` an den Support wenden

5xx und trace_id

Auch 5xx-Antworten nutzen dieselbe problem+json-Hülle. Die trace_id (auch im Header X-D2B-Trace-Id) entspricht 1:1 dem serverseitigen Stacktrace — bei Meldungen bitte mitschicken. Fehlgeschlagene asynchrone Ingest-Jobs tragen trace_id und die fehlgeschlagene Phase (phase) auch am Job-Datensatz.

Für Oberflächen, zu denen REST-Vokabular (GET /api/...) nicht passt, liefern betroffene Fehler zusätzlich suggested_fix_cli (im d2b ...-Vokabular). Die CLI zeigt automatisch diese Variante.