Fehlervertrag

Alle Fehler und fachlichen Warnungen verwenden einen einheitlichen Vertrag:

{
  "messageCode": "CONTRACT_STATE_INVALID",
  "severity": "ERROR",
  "params": {
    "contractId": "ctr_01J8ZK4T2M",
    "currentState": "TERMINATED",
    "attemptedAction": "APPROVE"
  },
  "traceId": "8f4a2c1e-9b3d-4e7f-a1c2-5d6e7f8a9b0c",
  "message": "The contract does not allow this action in its current state."
}

Feld	Typ	Beschreibung
messageCode	string	Stabiler, maschinenlesbarer Code. Bauen Sie Ihre Integrationslogik auf diesem Feld auf.
severity	ERROR | WARNING | INFO	Ob der Vorgang abgelehnt oder mit Vorbehalt akzeptiert wurde.
params	object	Strukturierte, codespezifische Parameter zum Rendern eigener Meldungen.
traceId	string	End-to-End-Trace-Id; geben Sie sie in Support-Anfragen an.
message	string	Anzeigefertiger Text, in der Anfragesprache aus dem Katalog aufgelöst.

Dreisprachiger Meldungskatalog

Das Feld message wird aus einem zentralen Katalog aufgelöst, der auf Türkisch, Englisch und Arabisch verfügbar ist, ausgewählt über Accept-Language (tr ist der Standard):

POST /api/v1/contracts HTTP/1.1
Accept-Language: en

Zwei Konsequenzen:

1. Kanäle erfinden nie eigene Texte. Portal, Konsole und Ihre Integration können für denselben messageCode denselben Text anzeigen.
2. Texte dürfen sich verbessern; Codes ändern sich nie. messageCode-Werte sind stabil und von der N-5-Kompatibilitätszusage abgedeckt.

HTTP-Statuscodes

Status	Bedeutung
400	Struktureller Validierungsfehler
401	Authentifizierung fehlgeschlagen / Token abgelaufen
403	Unzureichende Rolle/Berechtigung
404	Ressource nicht gefunden (innerhalb des Mandanten)
409	Fachlicher Konflikt (Zustandsmaschine, Vier-Augen-Prinzip, Idempotenz)
422	Fachliche Validierung fehlgeschlagen (z. B. abgeleitetes Feld übermittelt)
500	Unerwarteter Fehler — mit traceId melden