Fehler und Statuscodes
Diese Seite ist die konsolidierte Referenz für die Response-Envelopes, die jede Route der Kredit-API verwendet. Die Dokumentation pro Route nennt die Statuscodes, die eine bestimmte Route ausgibt; diese Seite dokumentiert die Form jedes Envelopes und den Katalog der benannten code-Werte, die Sie erhalten können.
Lesen Sie sie einmal vor der Integration und schlagen Sie dort nach, wann immer Sie ein Status ungleich 2xx überrascht.
Katalog der Statuscodes
| Status | Wann Sie ihn sehen | Beispielroute |
|---|---|---|
200 OK | Erfolgreicher Lesezugriff, idempotente Wiederholung, Soft-Stornierung, verarbeiteter Bulk-Batch, Statuswechsel. | Alle Routen außer Anlage-Routen. |
201 Created | Erfolgreiche Erstanlage über eine Einzeldatensatz-Route. | POST /borrowers. |
202 Accepted | Asynchroner Import gestartet – die Verarbeitung läuft im Hintergrund weiter. | POST /imports. |
204 No Content | Wird derzeit von keiner Route im Kreditbereich zurückgegeben. | — |
400 Bad Request | Validierungsfehler im Request: fehlerhaftes JSON, fehlerhafte Query, Schemaverletzung. | Alle schreibenden Routen. |
401 Unauthorized | Kein Authorization-Header, unbekanntes Token oder widerrufenes Token. | Alle Routen. |
403 Forbidden | Der Aufrufer ist ein Investor-Konto; Investoren können die Monitoring-Daten-API nicht nutzen (MONITORING_INVESTOR_FORBIDDEN). Ein ?unmask=true durch einen Nicht-Admin liefert kein 403, sondern 200 mit maskierten PII. | Alle Routen. |
404 Not Found | Ressource existiert nicht oder gehört zu einer anderen Organisation. | Alle Routen, die auf eine Ressource verweisen. |
409 Conflict | Eine aktive Zeile mit dieser id existiert bereits, oder ein Idempotency-Key wurde für einen anderen Statuswechsel wiederverwendet, oder die Commit-Phase konnte die hochgeladene Datei nicht sehen. | POST /borrowers, PATCH /loans/.../status, POST /imports/{id}/commit. |
413 Payload Too Large | Ein Bulk-NDJSON-Batch überschreitet das Zeilen- oder Byte-Limit. | POST /bulk/{entity}. |
422 Unprocessable Entity | Eine referenzierte Zeile existiert im selben Portfolio nicht als aktive Zeile (REFERENCED_ENTITY_NOT_FOUND), oder der angeforderte Statuswechsel ist nicht in der Übergangsmatrix enthalten (INVALID_STATUS_TRANSITION). Validierungsfehler verwenden 400. | POST /loans, POST /payments, PATCH /loans/{loanRef}/status. |
429 Too Many Requests | Rate Limit überschritten. Die Plattform wendet Rate Limits pro Organisation an; der Response-Header Retry-After gibt die Sekunden an. | Alle Routen. |
500 Internal Server Error | Unbehandelter Plattformfehler. Als vorübergehend behandeln; ein erneuter Versuch mit demselben Idempotency-Key ist sicher. | Alle Routen. |
Behandeln Sie jeden 4xx außer 429 als Fehler im Request – Ihre Client-Logik sollte die Eingabe verwerfen, statt es erneut zu versuchen. Behandeln Sie 429 und 500 als vorübergehend und versuchen Sie es mit Backoff erneut; ein Idempotency-Key macht den erneuten Versuch sicher.
Standard-Envelopes
Die Kredit-API verwendet drei Response-Envelopes für Statuscodes, die keinen Erfolg anzeigen. Die Form des Envelopes zeigt Ihnen, mit welcher Art von Fehler Sie es zu tun haben.
Validierungs-Envelope – 400 Bad Request
Wird für Schemaverletzungen, fehlerhafte Query-Parameter und fehlerhafte Pfade verwendet.
{
"error": "Validation failed",
"fieldErrors": [
{ "path": "interestRateApr", "message": "interestRateApr must be >= 0" },
{ "path": "termMonths", "message": "termMonths must be > 0" }
]
}| Feld | Typ | Hinweise |
|---|---|---|
error | string | Kurze, für Menschen lesbare Zusammenfassung. |
fieldErrors[].path | string | Punkt-Pfad zum fehlerhaften Feld. (root) steht für den Body selbst, z. B. wenn das JSON-Parsing fehlgeschlagen ist. |
fieldErrors[].message | string | Für Menschen lesbare Erklärung. |
Einige Routen geben bei Fehlern in Query-Parametern errors[] statt fieldErrors[] aus (die Framework-Konvention unterscheidet sich je nach Schnittstelle). Die path/message-Form ist identisch; behandeln Sie die beiden Array-Namen beim Parsen als austauschbar.
Envelope mit benanntem Code – 4xx
Wird verwendet, wenn der Fehler eine bestimmte Ursache hat, die die Plattform mit einem stabilen code-Wert benennt. fieldErrors ist optional und hängt davon ab, ob sich der Fehler einem bestimmten Feld zuordnen lässt.
{
"error": "a borrower with this id already exists",
"code": "ID_CONFLICT",
"fieldErrors": [
{ "path": "id", "message": "a borrower with this id already exists" }
]
}| Feld | Typ | Hinweise |
|---|---|---|
error | string | Für Menschen lesbare Zusammenfassung. |
code | string | Stabiler, maschinenlesbarer Code; siehe das Glossar. |
fieldErrors[] | array | fehlt | Vorhanden, wenn der Fehler auf ein bestimmtes Feld verweist. |
Einige Envelopes enthalten zusätzlichen strukturierten Kontext – zum Beispiel enthält batch_too_large einen fieldErrors-Block, der das überschrittene Limit nennt. Die Dokumentation pro Route führt diese auf.
Einfaches Fehler-Envelope – 404 / 401
Wird für knappe Responses verwendet, bei denen zusätzlicher Kontext dem Aufrufer nicht helfen würde. 404 ist das typische Beispiel:
{ "error": "Not found" }Einige Routen liefern { "error": "...", "code": "NOT_FOUND" }; behandeln Sie das Vorhandensein oder Fehlen von code bei einem 404 als informativ, nicht als tragend.
Zwei Code-Räume: Großschreibung vs. Kleinschreibung
Die Kredit-API verwendet zwei getrennte code-Namensräume, bewusst nach Aufnahmeform getrennt:
- Einzeldatensatz-Routen (POSTs, PATCHes, die Stornierung und die Abgleichs-GETs) geben
code-Werte inUPPER_CASEaus:ID_CONFLICT,PORTFOLIO_NOT_FOUND,REFERENCED_ENTITY_NOT_FOUND,INVALID_STATUS_TRANSITION,CHECK_VIOLATION,NOT_FOUND,UNKNOWN_KIND,COMMIT_FAILED,IDEMPOTENCY_CONFLICT,IDEMPOTENCY_KEY_REUSED,MONITORING_INVESTOR_FORBIDDEN. Die Bulk-NDJSON-Routen gebenMONITORING_INVESTOR_FORBIDDENebenfalls in Großbuchstaben zurück. - Bulk-NDJSON-Routen geben
code-Werte inlower_caseaus:batch_too_large,portfolio_not_found,portfolio_id_required,invalid_body,invalid_jsonsowie die unten dokumentierten Codes pro Zeile.
Wenn Sie in Ihrem Client nach code verzweigen, achten Sie exakt auf die Schreibweise. Die beiden Code-Räume sind jeweils für sich stabil; normalisieren Sie sie nicht.
Glossar der Fehlercodes
Die Plattform versieht jeden benannten Fehlerfall mit einem stabilen code. Verwenden Sie diese für programmatische Verzweigungen; der Text der error-Meldung kann sich ändern.
Code-Raum für Einzeldatensätze
| Code | Status | Ausgegeben von | Auslöser |
|---|---|---|---|
ID_CONFLICT | 409 | POST /borrowers, POST /loans, POST /payments. | Eine aktive Zeile mit derselben id existiert bereits. |
PORTFOLIO_NOT_FOUND | 404 | Alle schreibenden Einzeldatensatz-Routen. | Die portfolioId im Body existiert nicht in Ihrer Organisation. |
REFERENCED_ENTITY_NOT_FOUND | 422 | POST /loans, POST /payments. | borrowerId oder loanId verweist auf eine Zeile, die im selben Portfolio nicht als aktive Zeile existiert. |
INVALID_STATUS_TRANSITION | 422 | PATCH /loans/{loanRef}/status. | Das Paar aus Ausgangs- und Zielstatus ist nicht in der Übergangsmatrix enthalten. |
IDEMPOTENCY_CONFLICT | 409 | PATCH /loans/{loanRef}/status. | Der Idempotency-Key wurde bereits für einen anderen Statuswechsel verwendet. Senden Sie den neuen Statuswechsel mit einem neuen Schlüssel. |
IDEMPOTENCY_KEY_REUSED | 409 | POST /imports. | Der Idempotency-Key wurde bereits für einen Import mit anderen Anfrageparametern (kind, filename, sizeBytes, …) verwendet. Die Antwort enthält importId und mismatchedFields. Senden Sie den neuen Import mit einem neuen Schlüssel. |
MONITORING_INVESTOR_FORBIDDEN | 403 | Alle Monitoring-Routen für Kredite, einschließlich Bulk-NDJSON. | Der Aufrufer ist ein Investor-Konto; Investoren können die Monitoring-Daten-API nicht nutzen. |
CHECK_VIOLATION | 400 | POST /payments. | Eine Datenregel wurde verletzt (typischerweise die Invariante zum Forderungsverzicht; die Schemaebene lehnt dieselbe Form bereits bei der Validierung ab). |
NOT_FOUND | 404 | GET /borrowers/{id}, GET /payments/{id}, PATCH /loans/.../status, POST /payments/{id}/cancel, GET /loans/{externalId}. | Die gesuchte Zeile existiert im angegebenen Bereich nicht als aktive Zeile oder gehört zu einer anderen Organisation. |
UNKNOWN_KIND | 400 | POST /imports. | kind ist keine der sechs Kreditarten. Die Response enthält ein allowed-Array. |
COMMIT_FAILED | 409 | POST /imports/{id}/commit. | Die Plattform konnte die hochgeladene Datei nicht finden; typischerweise wurde der Upload nie abgeschlossen. Wiederholen Sie den Upload und committen Sie dann erneut. |
Code-Raum für Bulk-NDJSON
| Code | Status | Auslöser |
|---|---|---|
batch_too_large | 413 | Der Body überschreitet 10 000 Zeilen oder 10 MB. error und fieldErrors[].message unterscheiden zwischen Zeilen- und Byte-Limit. |
portfolio_id_required | 400 | ?portfolioId=<UUID> fehlt oder ist keine gültige UUID. |
portfolio_not_found | 404 | Die ?portfolioId= existiert in Ihrer Organisation nicht als aktives Portfolio. |
invalid_body | 400 | Der Request-Body konnte nicht als Text gelesen werden. |
invalid_json | (pro Zeile) | Eine Zeile ist kein gültiges JSON. Erscheint im errors[]-Array pro Zeile; der Batch liefert 200. |
Ein Code, der nicht in diesem Glossar steht, bedeutet, dass die Plattform seit der letzten Überarbeitung dieser Seite einen neuen benannten Code hinzugefügt hat. Protokollieren Sie den code-Wert immer unverändert zusammen mit dem Fehler Ihrer Anwendung, damit das Engineering-Team die Ereignisse zuordnen kann.
Fehlercodes pro Zeile (Bulk und asynchrone Importe)
Bulk-NDJSON und asynchrone Importe liefern beide Fehler pro Zeile. Die Bulk-Schnittstelle verwendet einen Satz von Werten; die Schnittstelle für asynchrone Importe verwendet einen ähnlichen, aber leicht abweichenden Satz (insbesondere validation_error statt validation_failed, da es sich um eine ältere Schnittstelle handelt). Einträge pro Zeile beschreiben Fehler einzelner Zeilen innerhalb eines erfolgreichen Batches, keine Envelope-Fehler.
Bulk-NDJSON-Codes pro Zeile
| Code pro Zeile | Auslöser |
|---|---|
validation_failed | Die Zeile hat die Schemavalidierung nicht bestanden. Das Feld message enthält die Validierungsfehler. |
fk_violation | Ein Fremdschlüsselverweis in der Zeile (z. B. borrowerId, loanId) verweist auf keine aktive Zeile im selben Portfolio. |
unique_violation | Eine aktive Zeile mit derselben (portfolio, externalId) oder id existiert bereits. (Es gibt keinen separaten Code id_conflict pro Zeile; beide Arten von Caller-ID-Kollisionen erscheinen hier.) |
check_violation | Eine Datenregel wurde verletzt – typischerweise die Regel zum Forderungsverzicht bei einer Zahlung. |
db_error | Ein unerwarteter Fehler beim Speichern dieser Zeile. Die Zeile wird als fehlgeschlagen gemeldet; der Batch läuft weiter. |
invalid_json | Die Zeile war kein gültiges JSON. Die Plattform verarbeitet den Rest des Batches. |
Codes pro Zeile bei asynchronen Importen
| Code pro Zeile | Auslöser |
|---|---|
parse_error | Die Zeile war kein gültiges JSON. |
validation_error | Die Zeile hat die Schemavalidierung nicht bestanden. |
portfolio_mismatch | Die portfolioId der Zeile entspricht nicht dem Anker-Portfolio des Imports. |
processor_error | Ein unerwarteter Fehler im Handler bei der Verarbeitung dieser Zeile. |
Fehler beim Speichern einer Zeile (ein fehlender Verweis, ein Duplikat, eine verletzte Datenregel) erscheinen unter einem der obigen Codes, mit den Details in errorMessage.
Fehler pro Zeile führen bei der Bulk-Schnittstelle nie zu einer Response ungleich 200 auf oberster Ebene – der Batch als Ganzes war erfolgreich, wenn der Request selbst wohlgeformt war; die Codes pro Zeile sagen Ihnen, was angekommen ist.
Semantik für erneute Versuche
Ein sicheres Muster für erneute Versuche bei jeder schreibenden Route ist:
- Erzeugen Sie pro logischer Operation einen deterministischen
Idempotency-Key. Eine UUIDv4 plus ein Routen-Unterscheidungsmerkmal funktioniert. - Senden Sie den Request mit dem Schlüssel.
- Bei
2xx,409 ID_CONFLICT,409 IDEMPOTENCY_CONFLICT,409 IDEMPOTENCY_KEY_REUSED,404,403,400,413oder422– nicht erneut versuchen. Das Ergebnis ist endgültig. - Bei
429– nach der im HeaderRetry-Afterangegebenen Dauer erneut versuchen. - Bei
500oder einem Netzwerkfehler – bis zu einer kleinen festen Anzahl von Malen mit exponentiellem Backoff erneut versuchen. DerIdempotency-Keymacht den erneuten Versuch sicher, unabhängig davon, ob der erste Versuch angekommen ist.
Ein erneuter Versuch eines erfolgreichen Requests mit demselben Idempotency-Key liefert dieselbe Response wie das Original, mit reused: true für die betroffene Entität. Das ist der kanonische Weg, sich von einem Netzwerkaussetzer zu erholen.
Was die Plattform nie zurückgibt
Für die operative Fehlersuche ist es nützlich, auch das zu kennen, was nicht vorkommt:
- Kein
5xx-Statuscode ist ein beabsichtigtes Verhalten der Plattform. Ein500ist immer ein zu behebender Bug; schreiben Sie nie Client-Logik, die von einer bestimmten500-Form abhängt. - Keine
404-Response legt Mandanteninformationen offen. Ein404für eine Zeile, die in einer anderen Organisation existiert, sieht genauso aus wie ein404für eine Zeile, die nirgends existiert. Schreiben Sie keine Client-Logik, die auf eine mandantenübergreifende Existenz schließt. - Keine Erfolgs-Response enthält ein Body-Feld namens
success: false. Der Statuscode ist maßgeblich dafür, ob der Aufruf erfolgreich war; die Body-Form liefert die Details. - Keine schreibende Route gibt ihre eigene UUID im Stil eines Pfadparameters zurück („Location“-Header). Die angelegte UUID erscheint im Feld
iddes Response-Bodys.