API-Fehler und was sie bedeuten
Was jeder HTTP-Status der Didit-API in der Praxis meistens bedeutet: 401 und 403 bei Schlüsseln und Berechtigungen, 402-artige Guthabenprobleme, 429 Rate Limits, und wie Sie den Fehlertext lesen.
Lesen Sie zuerst den Antworttext. Didits Fehler enthalten eine Nachricht und oft einen Detailcode, der das eigentliche Problem benennt - der Status allein reicht selten aus. 401 ist der Schlüssel, 403 sind Berechtigungen oder Umgebung, 429 ist Rate Limiting, und ein Guthabenfehler ist eine Frage der Credits, nicht des Codes.
#Zuerst den Text lesen
Der HTTP-Status nennt die Kategorie. Der Text sagt Ihnen, was passiert ist. Fast jede vermeidbare Debugging-Stunde bei einer API-Integration wird damit verbracht, einen Statuscode zu erraten, während die Antwort in einer verworfenen Response stand.
- Ein deaktivierter oder falscher Anwendungsschlüssel ist die übliche Ursache für einen 401.
- Zuletzt verwendet bestätigt, ob der Schlüssel, den Sie senden möchten, auch tatsächlich ankommt.
- Rotieren Sie das Secret, wenn ein Schlüssel geleakt sein könnte - ein 401 ist besser als ein Sicherheitsvorfall.
Protokollieren Sie den vollständigen Fehlertext - Status, Header und Payload - bei jedem fehlgeschlagenen Aufruf, in jeder Umgebung. Sie werden ihn brauchen, und er lässt sich später viel schwerer rekonstruieren.
#Was jeder Status meistens bedeutet
| Status | Übliche Ursache |
|---|---|
| 400 | Eine fehlerhafte Anfrage - ein fehlendes Pflichtfeld, ein ungültiger Enum-Wert, ein falsch geformtes verschachteltes Objekt |
| 401 | Authentifizierung fehlgeschlagen. Der Header x-api-key fehlt, ist fehlerhaft oder kein gültiger Schlüssel |
| 403 | Authentifiziert, aber nicht erlaubt. Falsche Umgebung, eine Berechtigung, die Ihr Schlüssel nicht hat, oder ein Feature, das für Ihr Konto nicht aktiviert ist |
| 404 | Die Ressource existiert nicht - oder existiert unter einer anderen Anwendung als der von Ihnen verwendete Schlüssel |
| 409 | Ein Konflikt mit bestehendem Zustand, etwa eine Aktion, die bereits ausgeführt wurde |
| 422 | Die Anfrage war formal korrekt, aber die Werte sind nicht akzeptabel - ein Validierungsfehler statt eines Syntaxfehlers |
| 429 | Rate Limit erreicht. Siehe unten |
| 5xx | Ein Problem auf Didits Seite. Wiederholen Sie mit Backoff und prüfen Sie status.didit.me |
#401 vs. 403 - die Unterscheidung, die Zeit spart
401 bedeutet, dass der Schlüssel überhaupt nicht akzeptiert wurde. Prüfen Sie, ob Sie x-api-key senden, dass der Wert keine überflüssigen Leerzeichen oder Anführungszeichen enthält, und dass Sie nicht versehentlich ein Webhook-Signing-Secret statt des API-Schlüssels eingefügt haben - das sind zwei verschiedene Dinge, und der Fehler kommt häufig vor.
403 bedeutet, dass der Schlüssel gültig ist, dieser Aufruf aber nicht erlaubt ist. Drei Ursachen, in dieser Reihenfolge:
- Umgebungs-Mismatch. Nur für Sandbox gedachte Felder (wie
sandbox_scenario) werden bei einer Live-Anwendung abgelehnt, und umgekehrt. Live und Sandbox sind getrennte Anwendungen mit getrennten Schlüsseln. - Fehlende Berechtigung. Manche Operationen benötigen Berechtigungen, die Ihr Schlüssel oder Ihre Rolle nicht besitzt. Wenn Sie Rechte zum Erstellen und Verwalten von Sessions benötigen, die Sie nicht haben, ist das eine Anfrage an den Support, keine Code-Korrektur.
- Feature nicht aktiviert. Manche Funktionen werden pro Organisation bereitgestellt. Ein 403 bei einem Feature, von dem Sie glauben, dass Sie es haben sollten, lohnt eine Nachfrage, bevor Sie den Aufruf umschreiben.
Es gibt keine eingebaute Möglichkeit, einen Sandbox-Schlüssel allein am Aussehen von einem Live-Schlüssel zu unterscheiden. Speichern Sie sie deshalb unter klar unterscheidbaren Namen in Ihrem Secret Manager und lassen Sie niemals eine einzelne Umgebungsvariable "den jeweils aktuellen Schlüssel" halten. Ein Live-Schlüssel in einer Testumgebung verbraucht echte Credits.
#404, obwohl die Ressource existieren sollte
Wenn eine Session oder ein Workflow einen 404 zurückgibt und Sie sicher sind, dass sie existiert, liegt die übliche Antwort darin, dass sie unter einer anderen Anwendung existiert als der Schlüssel, mit dem Sie sich authentifiziert haben. Ressourcen sind an ihre Anwendung gebunden; ein Schlüssel von Anwendung A kann die Sessions von Anwendung B nicht sehen.
#Guthaben- und Credit-Fehler
Ein Aufruf, der scheitert, weil nicht genug Credits vorhanden sind, ist kein Code-Problem. Der Workflow enthält ein kostenpflichtiges Feature, und Ihr Guthaben deckt es nicht ab. Das ist bei weitem die häufigste "die API ist kaputt"-Meldung, und die Ursache ist fast immer White Label, AML oder NFC in einem Workflow, von dem erwartet wurde, dass er kostenlos ist. Siehe einen "nicht genug Credits"-Fehler beheben.
#429 Rate Limiting
Limits werden pro Kennung angewendet - Ihrem x-api-key, oder Ihrer Client-IP, wenn kein Schlüssel gesendet wird - mit einem unabhängigen Zähler pro Scope in einem gleitenden 60-Sekunden-Fenster.
Globale Standardwerte:
| Scope | Methoden | Limit |
|---|---|---|
| Generische Lesezugriffe | GET | 600 / min |
| Generische Schreibzugriffe | POST, PATCH, DELETE | 300 / min |
Manche stark genutzten Endpunkte haben zusätzlich zum globalen Limit strengere Grenzen, und der erste Scope, dessen Zähler überschritten wird, ist derjenige, der einen 429 zurückgibt. Vollständige Tabelle: Rate Limiting.
Behandeln Sie 429 mit exponentiellem Backoff und Jitter. Eine enge Retry-Schleife gegen ein Rate Limit verschlimmert das Problem und kann Sie dauerhaft limitiert halten.
Batch-Jobs sind die übliche Quelle eines 429 - ein nächtlicher Import, der innerhalb weniger Sekunden mehrere hundert Erstellungen auslöst. Verteilen Sie die Arbeit, statt die Nebenläufigkeit zu erhöhen, bis der Fehler aufhört.
#Detailcodes auf Feature-Ebene
Über HTTP-Statuscodes hinaus geben einzelne Prüfungen eigene Detailcodes für Probleme auf Provider-Ebene zurück - etwa eine Registry-Integration, die für ein bestimmtes Produkt in einem bestimmten Land keinen Zugriff hat. Wenn Sie einen solchen Code erhalten, benennt er die Situation präzise, zitieren Sie ihn also, wenn Sie danach fragen.
Wenn eine Antwort einen Detailcode auslässt, den Sie aus dem Katalog erwarten würden, lohnt sich eine Meldung, statt es zu umgehen - ein fehlender Code ist eine echte Lücke, und er macht dasselbe Problem für die nächste Person schwerer.
#Leere Antworten sind kein Erfolg
Eine providergestützte Prüfung, die einen leeren Body zurückgibt, ist nicht dasselbe wie ein sauberes Ergebnis. Behandeln Sie "keine Daten" in Ihrem Code als eigenen Fall, statt es auf ein Bestehen abzubilden - besonders bei Database Validation und Wallet Screening, wo ein nicht bereitgestellter Dienst und ein echter Non-Match von außen ähnlich aussehen können.
#Fehlerpfade testen
Die Sandbox erzwingt bestimmte Fehler deterministisch, was die einzig sinnvolle Art ist, Ihre Fehlerbehandlung zu testen. Siehe Testen in der Sandbox.