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
`artifact_expired`	Export oder Artefakt neu erstellen und die neue Download-URL nutzen.
`authentication_failed`	Fehlendes, fehlerhaftes, widerrufenes oder abgelaufenes Credential ersetzen.
`authorization_failed`	Credential mit passendem Scope, passender Rolle oder Org-Berechtigung nutzen.
`browser_auth_disabled`	Kein client-seitiger Retry; Browser-Anmeldung ist im Deployment nicht konfiguriert.
`browser_auth_provider_disabled`	Anmeldung neu starten und eine von Cognito angezeigte Option verwenden; die Registrierung wird gezielt ausgerollt.
`billing_checkout_preparing`	Auf `retryAfterMilliseconds` warten und dieselbe Anfrage mit demselben Idempotency-Key wiederholen.
`billing_checkout_terminal_recovery`	Einen neuen bezahlten Checkout-Versuch starten; bei Supportkontakt die `requestId` angeben.
`conflict`	Resource State aktualisieren und nur wiederholen, wenn sich der Konflikt geloest hat.
`csv_parse_failed`	Hochgeladene CSV korrigieren und Upload neu erstellen oder wiederholen.
`dataset_artifact_unavailable`	Nicht retrybar; Dataset neu hochladen oder ersetzen (`suggestedAction: replace_dataset`).
`dataset_identity_index_unavailable`	Retrybar; Upload-Verarbeitung erneut ausloesen, ohne die Datei neu zu senden.
`dataset_intake_state_invalid`	Upload Processing wiederholen, wenn der gespeicherte Processing State neu aufgebaut werden kann.
`dataset_intake_unavailable`	Dataset Intake spaeter erneut versuchen.
`dataset_registration_failed`	Neuen Upload erstellen oder Support mit der Upload-ID kontaktieren.
`export_expired`	Neuen Export erstellen.
`export_failed`	Export Failure pruefen und nach Behebung einen neuen Export erstellen.
`export_not_ready`	Export pollen, bis er ready ist, bevor Download versucht wird.
`file_too_large_for_multipart`	Kleinere CSV oder spaeteren resumable Upload Path nutzen.
`idempotency_conflict`	Idempotency Keys nur fuer identische Requests wiederverwenden oder neuen Key senden.
`internal_error`	`requestId` bewahren und nach Erholung des Service wiederholen.
`invalid_state`	Resource aktualisieren und eine Operation waehlen, die fuer den aktuellen State gueltig ist.
`invitation_already_accepted`	Mit dem akzeptierten Account anmelden oder neue Einladung anfordern.
`invitation_conflict`	Einladungsstatus pruefen und bei Bedarf neue Einladung senden.
`invitation_email_mismatch`	Mit der eingeladenen E-Mail-Adresse anmelden.
`invitation_expired`	Neue Einladung anfordern oder senden.
`invitation_revoked`	Neue aktive Einladung anfordern oder senden.
`last_owner_conflict`	Einen anderen Owner hinzufuegen oder hochstufen, bevor der aktuelle entfernt wird.
`no_retryable_rows`	Fehlgeschlagene, geflaggte oder retryable skipped Rows auswaehlen, bevor ein Retry Run erstellt wird.
`not_found`	ID, Pfad und authentifizierte Organisation pruefen.
`query_result_not_ready`	Pollen solange nicht terminal; bei `succeeded` das Ergebnis lesen, bei `failed` den Fehler pruefen.
`rate_limited`	Warten und mit Backoff erneut versuchen.
`run_already_terminal`	Retry oder Follow-up Run erstellen, statt den terminalen Run zu mutieren.
`run_analysis_snapshot_not_ready`	Pollen, solange `details.status` `queued` oder `processing` ist; bei `failed` aufhoeren.
`run_not_terminal`	Warten, bis der Run terminal ist, bevor terminal-only Operationen genutzt werden.
`run_paused`	Pausierten Run fortsetzen oder abbrechen.
`service_unavailable`	Wiederholen, wenn Dependency oder Readiness Problem behoben ist.
`session_expired`	Erneut anmelden, um eine frische Browser Session zu erhalten.
`transient_intake_failure`	Wiederholen, wenn die Upload-Quelle noch wiederherstellbar ist.
`unauthenticated`	Nutzer durch die Anmeldung fuehren; bei anonymem Browser erwartet.
`upload_already_completed`	Das fertige Dataset nutzen, statt den Upload zu wiederholen.
`upload_expired`	Neuen Upload erstellen.
`upload_processing`	Warten, bis das aktuelle Processing beendet ist.
`upload_processing_failed`	Sichere Failure Metadata pruefen und nur wiederholen, wenn retryable.
`upload_source_expired`	Neuen Upload erstellen, weil die ursprüngliche Quelle abgelaufen ist.
`upload_source_metadata_mismatch`	Upload mit passenden File Metadata neu erstellen.
`upload_source_size_mismatch`	Upload mit korrekter Dateigroesse neu erstellen.
`upload_source_unavailable`	Processing spaeter wiederholen, wenn die Quelle noch lesbar ist.
`validation_failed`	Request-Form, Feldwerte, Schema, Header oder Multipart-Metadaten korrigieren.

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.