Stabiler Ursachencode
Ein stabiler Fehlercode wird in Client-Logik, Reporting und automatischer Weiterleitung von Anfragen verwendet.
Dokumentation / API-Fehler
API-Fehlerbehandlung
Ein einheitliches Modell für Antworten, Fehlercodes, temporäre Störungen, unbekannte Ergebnisse, Diagnose und sichere Wiederherstellung bei iGaming-Integrationen.
HTTP
Anfrageergebnis
Codes
klare Ursache
Wiederholung
sichere Aktion
Trace
Anfragediagnose
Zyklus der Fehlerbehandlung
Von der API-Antwort bis zur Wiederherstellung
01
Ergebnistyp bestimmen
HTTP-Status, Ursachencode, Fehlerkategorie und Operationsstatus prüfen.
02
Daten für die Analyse speichern
Anfrage- und Operationskennungen, Endpoint, Zeit, Provider-Referenz und sichere Parameter protokollieren.
03
Sichere Aktion auswählen
Daten korrigieren, Operation stoppen, nach einer Pause erneut versuchen oder aktuellen Status prüfen.
04
Wiederherstellen und kontrollieren
Duplikate verhindern, Ergebnisse abstimmen, zuständige Teams benachrichtigen und die Ursache abschließen.
Übersicht
Ein Fehler sollte Ursache und nächste Aktion erklären
Eine HTTP-400- oder HTTP-500-Antwort allein reicht nicht aus. Eine zuverlässige API liefert einen stabilen Ursachencode, verknüpft die Antwort mit einer Anfragekennung und macht deutlich, ob Daten korrigiert, die Operation gestoppt, die Anfrage wiederholt oder ihr Status separat geprüft werden muss.
Vorhersehbare Aktion
Die Fehlerkategorie zeigt, ob die Anfrage wiederholt werden kann und welche Daten geändert werden müssen.
Diagnostische Verknüpfung
Anfrage-, Operations- und Provider-Kennungen verknüpfen Client-Logs mit internen Systemen und Support.
Fehlerstruktur
Empfohlene Struktur einer Fehlerantwort
Die Antwort sollte kompakt, stabil und für automatisierte Verarbeitung geeignet sein, ohne interne Implementierung oder sensible Daten offenzulegen.
Fehlercode
Eine stabile Kennung der Ursache, die sich bei Änderungen der erläuternden Nachricht nicht ändert.
Beschreibung
Eine kurze, sichere Erklärung ohne internen Code, Datenbankabfragen, Geheimnisse oder unnötige Details.
Anfrage-ID
Eine eindeutige Kennung zum Auffinden der Operation in Logs und für Supportanfragen.
Zusätzliche Daten
Ein zulässiger Status, ein Limit, der aktuelle Zustand oder ein sicherer Ablehnungsgrund.
Wiederholbar
Ein eindeutiger Hinweis auf einen temporären Fehler, der den Duplikatschutz der Operation nicht aufhebt.
Pause vor der Wiederholung
Eine empfohlene Verzögerung in Sekunden oder ein HTTP-Header für Ratenbegrenzung und vorübergehende Nichtverfügbarkeit.
Feldfehler
Liste problematischer Felder mit Ursachencode, Pfad zum Wert und sicherer Erläuterung.
Verweis auf die Dokumentation
Ein permanenter Link oder eine Abschnittskennung mit Beschreibung der Ursache und der Korrekturmethode.
Fehlerkategorien
Hauptkategorien von Fehlern
Der HTTP-Status zeigt die allgemeine Ergebnisklasse, während der interne Code die konkrete Ursache und zulässige Aktion angibt.
Fehler bei der Eingabevalidierung
Ungültiges Format, fehlendes Pflichtfeld, nicht unterstützter Wert, falsche Betragspräzision oder ungültige Anfragestruktur.
Authentifizierungsfehler
Fehlender, abgelaufener oder ungültiger Token, API-Schlüssel, Signatur, Anfragezeitstempel oder Nonce.
Unzureichende Berechtigungen
Der Client ist erkannt, verfügt aber nicht über die erforderliche Rolle, Marke, den Markt oder die Berechtigung für die Aktion.
Objekt nicht gefunden
Ein Spieler, eine Zahlung, Runde, KYC-Prüfung, ein Provider oder anderes Objekt existiert nicht oder steht dem Client nicht zur Verfügung.
Statuskonflikt
Version oder Status des Objekts haben sich geändert oder die Operationskennung wurde bereits mit anderen Parametern verwendet.
Verstoß gegen Geschäftsregel
Unzureichendes Guthaben, überschrittenes Limit, gesperrter Spieler, verbotener Markt oder unzulässiger Statuswechsel.
Zu viele Anfragen
Die zulässige Anzahl von Anfragen für Client, Methode, Rolle oder kritische Operation wurde überschritten.
Provider nicht verfügbar
Der externe Dienst ist nicht verfügbar, antwortet verzögert oder nimmt vorübergehend keine Operationen an.
Interner Fehler
Ein unerwarteter Plattformfehler ohne Offenlegung interner Details, aber mit einer Kennung für die Diagnose.
Wiederholungen und Wiederherstellung
Anfragewiederholung und unbekanntes Ergebnis
Eine Wiederholung ist nur sicher, nachdem der Fehlertyp bestimmt und geprüft wurde, ob die ursprüngliche Operation bereits abgeschlossen sein könnte.
01
Prüfen, ob eine Wiederholung zulässig ist
Daten-, Berechtigungs- und Geschäftsregelfehler erfordern in der Regel eine Korrektur der Anfrage statt eines erneuten Sendens.
02
Denselben Operationsschlüssel beibehalten
Die Wiederholung einer finanziellen, spielbezogenen oder anderen kritischen Operation darf kein neues Ergebnis erzeugen.
03
Pause zwischen Versuchen erhöhen
Die Intervalle werden schrittweise erhöht, berücksichtigen die serverseitig angegebene Verzögerung und begrenzen die Gesamtzahl der Versuche.
04
Stoppen und zur Prüfung eskalieren
Nach Ausschöpfung aller Versuche wird die Operation als unvollständig erfasst und zur manuellen Prüfung oder Abstimmung weitergeleitet.
Keine Antwort bedeutet nicht, dass die Operation fehlgeschlagen ist
Wenn die Verbindung nach dem Senden einer Anfrage abbricht, kann das Ergebnis unbekannt bleiben. Vor einer Wiederholung den Status über die Operationskennung prüfen oder auf eine vertrauenswürdige Benachrichtigung warten.
Diagnose und Kontrolle
Logs, Kennungen, Metriken und Warnungen
Die Diagnose sollte den Anfragepfad zwischen Plattform, Adapter und externem Provider rekonstruieren, ohne unnötige sensible Daten zu speichern.
Kontext für die Analyse
Anfrage-, Korrelations-, Operations- und externe Provider-Kennungen.
Endpoint, HTTP-Methode, Umgebung, Client, Zeit und Antwortdauer.
HTTP-Status, Fehlercode, Anzahl der Versuche und finaler Status.
Maskierte sensible Felder, sichere Header und Ergebnis der Signaturprüfung.
Monitoring und Warnungen
Fehlerrate nach Methode, Provider, Client und Ursachenkategorie.
Anstieg langsamer Antworten, HTTP-5xx-Fehler, ungültiger Signaturen und Rate-Limit-Ereignisse.
Anzahl der Wiederholungen, Operationen mit unbekanntem Ergebnis und Wiederherstellungsaufgaben.
Warnungen mit Schwellenwerten, Verantwortlichen und Eskalationsregeln.
Tests
Was in der Testumgebung geprüft werden muss
Die Testumgebung sollte jede wichtige Fehlerkategorie reproduzieren und das korrekte Verhalten von Client, Wiederholungen und Kontrollen bestätigen.
Fehler bei der Eingabevalidierung
Fehlende Felder, ungültige Typen, nicht unterstützte Werte, Betragspräzision und mehrere gleichzeitige Fehler.
Zugriff und Berechtigungen
Ungültiger Schlüssel, abgelaufener Token, falsche Signatur, unberechtigte Rolle, gesperrte IP und erneut verwendete Nonce.
Keine Antwort und unbekanntes Ergebnis
Verbindungsabbruch vor dem Senden, nach Annahme der Operation und während des Empfangs der finalen Antwort.
Ratenbegrenzung
HTTP 429, empfohlene Pause, parallele Anfragen und Wiederherstellung nach Ablauf der Begrenzung.
Provider-Fehler
Nichtverfügbarkeit, Wartung, ungültige Antwort, verzögerte Benachrichtigung und widersprüchlicher Status.
Wiederholung und Schutzstopp
Begrenzung der Versuchszahl, zunehmende Pausen, vorübergehendes Stoppen von Anfragen, kontrollierte Wiederherstellung und manuelle Eskalation.
Checkliste vor dem Start
Eine Produktivintegration wird gestartet, nachdem Fehlerstruktur, Client-Verhalten, Duplikatschutz und Diagnose geprüft wurden.
Alle Fehler liefern einen stabilen Ursachencode und eine Anfragekennung.
Fehlerdetails legen keine Geheimnisse oder interne Implementierung offen.
Temporäre und dauerhafte Fehlerkategorien sind dokumentiert.
Eine wiederholte kritische Operation verwendet denselben Idempotenzschlüssel.
Ein unbekanntes Ergebnis wird durch Statusprüfung oder eine vertrauenswürdige Benachrichtigung behandelt.
Logs, Metriken, Warnungen, eine Wiederherstellungswarteschlange und Eskalationsregeln sind eingerichtet.
API-Fehler vereinheitlichen?
Senden Sie uns Ihre aktuellen HTTP-Antworten, Fehlercodes, Wiederholungsregeln und problematischen Szenarien. APIACE hilft, ein einheitliches Fehlermodell, sichere Wiederherstellung und Kontrollmechanismen festzulegen.