Fehlerreferenz

Öffentliche Fehlercodes, Recovery-Entscheidungen und Docs-URLs für Everyn-Clients.

Everyn-Fehler sollen behebbar und verlinkbar sein. Öffentliche API-Fehler enthalten einen stabilen code, eine lesbare message, eine requestId, eine docsUrl und optionale fieldErrors. Dataset-Upload-Failures zeigen außerdem öffentlich sichere Failure Metadata auf der Ressource selbst.

Nutze diesen Bereich als Recovery Hub. Nutze API-Fehler, wenn du die genaue HTTP-Envelope-Form brauchst. Nutze spezifische Error-Code-Seiten, wenn ein Fehler eine docsUrl enthält.

Fehler lesen und beheben

Wie man einen Everyn-Fehler liest

Feld	Bedeutung	Was tun
`status`	HTTP-Status-Kategorie.	Einordnen, ob Validation, Auth, State, Retry oder Internal.
`code`	Stabiler maschinenlesbarer Fehler.	Passende Docs-Seite öffnen, wenn verfügbar.
`message`	Lesbare Zusammenfassung.	Zitieren oder paraphrasieren, ohne den Code zu verlieren.
`requestId`	Support- und Trace-Kennung.	In Bug Reports oder Support-Zusammenfassungen bewahren.
`docsUrl`	Kanonische Recovery-Seite.	Vor Empfehlung lesen.
`fieldErrors`	Feld-, Header-, Parameter- oder Form-spezifische Probleme.	Exaktes betroffenes Feld und erwartete Form nennen.

Recovery-Entscheidungstabelle

Situation	Retry?	Bessere nächste Handlung
Ungültiges JSON, fehlendes Pflichtfeld, ungültiger Column Name, unsupported Model.	Nein.	Request oder Job Spec korrigieren, dann neuen Request senden.
Fehlendes, fehlerhaftes, widerrufenes oder abgelaufenes Credential.	Nein.	Credential ersetzen.
Gültiger Principal ohne erforderlichen Scope oder Rolle.	Nein.	Credential mit passender Berechtigung nutzen.
Organisationsfremde oder fehlende Ressource.	Kein blinder Retry.	Prüfen, ob die ID zur authentifizierten Organisation gehört.
Idempotency-Fingerprint-Konflikt.	Nicht mit demselben Key.	Key nur für exakt denselben Request wiederverwenden oder neuen Key senden.
Export noch nicht ready.	Pollen.	Export lesen, bis er ready ist, bevor Download versucht wird.
Transienter Intake Failure.	Vielleicht.	Nur wiederholen, wenn die Upload-Quelle noch existiert und der Fehler retryable ist.
Interner oder Upstream-Ausfall.	Nach Erholung.	`requestId` bewahren und nach Erholung des Service wiederholen.

Spezifische Fehlerseiten

Code	Typischer nächster Schritt
`validation_failed`	Request-Form, Feldwerte, Schema, Header oder Multipart-Metadaten korrigieren.
`csv_parse_failed`	Hochgeladene CSV korrigieren und Upload neu erstellen oder wiederholen.
`transient_intake_failure`	Wiederholen, wenn die Upload-Quelle noch wiederherstellbar ist.
`upload_source_expired`	Neuen Upload erstellen, weil die ursprüngliche Quelle abgelaufen ist.

Beziehung zu API-Fehlern

Diese Seite beantwortet: "Was sollte der Client als Nächstes tun?" Die Seite API-Fehler beantwortet: "Wie sieht die HTTP Error Envelope aus?"

Sicherheitsregeln

Nie API Keys, Webhook Secrets, Auth Headers, Secret Hashes, Object-Store Pointer, Signed URLs, Stack Traces, Source Rows oder Generated Outputs in einer Fehlerzusammenfassung offenlegen.
Nicht ableiten, ob eine Ressource in einer anderen Organisation existiert.
Nicht-retryable Validation-, Authentication- oder Authorization-Fehler nicht wiederholen.
requestId für Support Escalation sichtbar halten.