Häufige API-Probleme

Fast jeder API-Supportfall ist eines von rund zehn Dingen. Das hier ist die Liste, in der Reihenfolge des Prüfens, mit dem Fix statt der Theorie.

Zuerst den Fehler lesen

Jeder Fehler kommt in derselben Form zurück:

{ "error": true, "message": "missing X-Revenexx-Tenant header" }

Die message ist meist konkret genug, um das Problem allein zu lösen. Lesen Sie sie, bevor Sie eine Theorie bilden. Und nehmen Sie die X-Request-ID aus den Antwort-Headern mit — sie macht aus einem Supportfall statt eines Gesprächs eine Antwort.

Statuscode zu Ursache

Manche Apps beantworten eine gescheiterte Feldvalidierung mit 422 statt 400. Behandeln Sie beide gleich: Der Request wurde verstanden und abgelehnt, und keiner von beiden sollte unverändert wiederholt werden.

401 direkt nach dem Anlegen eines Schlüssels

Fast immer die Kopie, nicht der Schlüssel. Lange Secrets werden von Chat-Clients, Tabellenzellen und Terminal-Umbrüchen abgeschnitten. Widerrufen und neu ausstellen statt debuggen; das dauert zwei Minuten, die Alternative einen Nachmittag.

Die andere Ursache: zwei Credentials auf einmal gesendet. Senden Sie entweder X-Revenexx-Api-Key oder Authorization: Bearer …, nie beide.

403 bei manchen Aufrufen, bei anderen nicht

Das ist eine Scope-Lücke, und sie ist eine gute Nachricht — der Schlüssel funktioniert, er darf nur dieses eine Ding nicht. Die Message benennt die Capability. Ergänzen Sie diesen Capability-Scope am Schlüssel, oder stellen Sie einen neuen mit ihm aus.

Widerstehen Sie der Versuchung, „erst mal" auf * zu weiten. Siehe Schlüssel, Berechtigungen und Tenants.

Der andere 403-Fall: Die App, die die Capability implementiert, ist nicht installiert, oder der Aufrufer ist kein Mitglied des Tenants.

429, das nicht weggeht

Vereinzelte 429 sind normal und heißen: Ihr Backoff funktioniert. Ein steter Strom heißt: Etwas ist falsch entworfen.

Prüfen Sie drei Dinge, in dieser Reihenfolge:

1. Loopt etwas? Ein Job, der einen Request je Artikel macht, ist der übliche Verdächtige. Er sollte ein Bulk-Job sein — siehe Rate-Limits, Kontingente und Fair Use.
2. Läuft etwas anderes zur selben Zeit? Das Limit gilt je Tenant, nicht je Schlüssel. Ihr BI-Abzug und Ihr ERP-Sync konkurrieren, und Ihre Storefront ebenso.
3. Weicht der Client mit Jitter zurück? Parallele Worker, die im Gleichschritt wiederholen, erzeugen die Spitze neu, die das 429 verursacht hat.

Der Webhook, der nie ankommt

Arbeiten Sie diese Liste ab. Sie steht in der Reihenfolge, die am schnellsten auflöst.

1. Ist das Event passiert? In Events › Event Stream nachsehen. Steht das Event nicht dort, ist das kein Webhook-Problem.
2. Abonniert irgendetwas das Topic? Der Abschnitt Routed to des Events beantwortet das. „Kein Ziel abonniert dieses Topic" ist die häufigste Antwort, und der Fix ist ein Abonnement, keine Debugging-Sitzung.
3. Ist das Ziel aktiviert? Ein dauerhaft gescheitertes Ziel wird automatisch deaktiviert. Wiederaktivieren spielt das Verpasste nicht nach.
4. Was sagen die Delivery attempts? Anhaltend 4xx sind Ihr Payload oder Ihre Credentials; anhaltend 5xx ist deren System; Timeouts heißen: Der Empfänger ist zu langsam.
5. Ist der Empfänger aus dem Internet überhaupt erreichbar? Siehe den Firewall-Abschnitt unten.
6. Kam es an und wurde verworfen? Ein Empfänger, der eine nicht verifizierte Signatur ablehnt, antwortet 401 — von Ihrer Seite sieht das wie ein Zustellfehler aus und ist ein Verifikationsfehler auf seiner.

Die Signatur, die nie passt

Vier Ursachen, sortiert danach, wie oft sie sich als die Antwort erweisen.

1. Der Body wurde neu serialisiert. Mit Abstand am häufigsten. Die Signatur deckt die rohen Request-Bytes, exakt wie empfangen. Ein Framework, das JSON parst und vor der Verifikation neu kodiert, ändert Leerraum oder Schlüsselreihenfolge, und nichts wird je passen. Greifen Sie den rohen Body vor jedem Parsing ab.

2. Das falsche Secret. Ein Secret vom falschen Ziel kopiert, oder eines, das nur auf einer Seite rotiert wurde.

3. Rotation nicht behandelt. Während einer Rotation kann der Signatur-Header mehr als eine kommagetrennte Signatur tragen. Ein Empfänger, der nur die erste liest, lehnt die Hälfte der Zustellungen ab. Akzeptieren Sie die Zustellung, wenn eine Signatur passt.

4. Kodierung. HMAC-SHA256, hexadezimal, verglichen gegen den Wert nach v0=. Base64 wird nie zu Hex passen.

Uhrendrift

Prüft der Empfänger den Zustell-Zeitstempel — und das sollte er —, lehnt eine driftende Uhr völlig gültige Zustellungen ab. Das Symptom ist unverkennbar: Alles scheitert, auf einmal, ohne Konfigurationsänderung, und die Fehlschläge sind 401 vom Empfänger, keine Fehler der Plattform.

Beheben Sie es an der Quelle: NTP auf dem empfangenden Host. Weiten Sie nicht das Toleranzfenster zur Kompensation, denn das Fenster ist es, was das spätere Abspielen einer alten mitgeschnittenen Zustellung verhindert.

Dasselbe gilt für signierte Download-URLs eines Exports: Sie sind kurzlebig, und eine Maschine mit falscher Uhr hält eine gültige URL für abgelaufen.

Firewall und Egress

Das Problem, das sich immer als „die API ist kaputt" präsentiert und immer eine Netzwerkregel ist.

Eingehend zu Ihrem Empfänger. Ein Webhook-Ziel muss aus dem öffentlichen Internet erreichbar sein, über HTTPS, mit validierendem Zertifikat. Endpoints hinter einem Firmen-VPN, auf einem .local-Namen oder in einem privaten IP-Bereich werden nie etwas empfangen. Ein Endpoint, der ein Client-Zertifikat verlangt, ebenso wenig.

Ausgehend von Ihren Systemen. Eine Maschine, die api.revenexx.com aufruft, braucht ausgehendes HTTPS auf Port 443. In einem Mittelstands-Netzwerk ist das oft standardmäßig blockiert, und das Symptom ist ein Verbindungs-Timeout, kein HTTP-Fehler.

Proxys, die Requests umschreiben. Ein Firmen-Proxy, der unbekannte Header entfernt, nimmt X-Revenexx-Tenant heraus, und Sie bekommen 400 mit der Meldung, der Header fehle — während der Integrator auf Code schaut, der ihn eindeutig setzt. Das ist der am schwersten zu findende Fall, und die Message ist der Hinweis.

Eine Drei-Minuten-Triage, die all das trennt:

Machen Sie alle drei, bevor jemand ein Ticket öffnet. Das räumt die meisten Fälle sofort ab und sagt Ihnen, wessen Problem der Rest ist.

Degradiert, nicht kaputt

Zwei Antwort-Header lohnen sich zu kennen, weil sie sonst rätselhaftes Verhalten erklären:

• X-Capability-Degraded — eine Fallback-Implementierung hat den Request bedient. Es hat funktioniert, aber nicht über den üblichen Pfad. Anhaltende Degradierung ist einen Supportfall wert, obwohl nichts fehlschlägt.
• X-Cache: HIT — die Antwort kam aus dem Cache. Scheint ein Schreibzugriff beim nächsten Lesen nicht zu wirken, prüfen Sie das zuerst.

Wann Sie einen Supportfall öffnen

Sie haben den Statuscode und seine Message geprüft, den Schlüssel und seine Scopes bestätigt, den Netzwerkpfad von der aufrufenden Maschine bestätigt, und der Fehler ist reproduzierbar. Bringen Sie mit:

• Die X-Request-ID einer fehlschlagenden Antwort.
• Den Tenant-Slug, den Schlüsselnamen (nie das Secret), und den exakten Pfad samt Methode.
• Wann es begann, und was sich um diesen Zeitpunkt geändert hat.
• Bei einem Webhook: die Event-Id und den Namen des Ziels.

Weiter

• Integrationen überwachen — das hier finden, bevor es jemand meldet.
• Mit API-Änderungen umgehen — die Fehler, die vorab angekündigt waren.