HTTP-Fehler-Triage (HTTP error triage)
Ein HTTP-Fehler sagt Ihnen, dass eine Anfrage fehlgeschlagen ist. Meistens sagt er Ihnen nicht, warum. Aus einem 403 zu schließen "der Schlüssel ist tot" ist eine Vermutung, die eine Zahl trägt.
Entstanden aus einem echten Vorfall (2026-07-30): Eine Drittanbieter-API zur Kontaktanreicherung gab für sechs Tage bei jedem Aufruf 403 error code: 1010 zurück. Dies wurde als "Schlüssel nicht berechtigt", "Guthaben aufgebraucht", "monatliches Kontingent erreicht" gedeutet. Auf dieser Annahme basierend wurde eine 756-zeilige Browser-Automatisierungs-Workaround gebaut, und ein Kunde wurde beinahe gebeten, einen Tarif zu überprüfen, der in Ordnung war. Die eigentliche Ursache war ein fehlender User-Agent, weshalb das CDN den Client am Edge sperrte. Ein Header behob das Problem: 200 OK, volle Daten, und das Guthaben war die ganze Zeit vorhanden.
Führen Sie diese drei Kontrollen vor Ihrer Diagnose durch
1. Die Kontrolle mit ungültigen Anmeldedaten. Senden Sie die gleiche Anfrage mit einem absichtlich ungültigen Schlüssel und noch einmal ganz ohne Schlüssel.
for label, key in [("real", REAL_KEY), ("garbage", "0"*36), ("empty", "")]:
... # gleiche URL, gleiche Methode, gleiche Header
Wenn alle drei den gleichen Status und Body zurückgeben, liegt der Fehler nicht an Ihrem Schlüssel. Er enthält keine Informationen über Berechtigung, Kontingent oder Gültigkeit. Hören Sie auf, über den Schlüssel nachzudenken.
2. Die Kontrolle mit einem nicht existierenden Pfad. Fragen Sie einen Pfad an, der definitiv nicht existiert, und die Startseite der Website.
GET https://api.example.com/definitely-not-a-real-path-12345
GET https://api.example.com/
GET https://www.example.com/ # deren Marketing-Seite
Wenn der API-Fehler auch von der Marketing-Seite zurückkommt, werden Sie vor dem Origin-Server blockiert. Nichts am API-Aufruf wird helfen.
3. Lesen Sie die Antwort-Header, nicht nur den Body.
except urllib.error.HTTPError as e:
print(e.code, e.headers.get("server"), e.read()[:200])
server: cloudflare bei einem "auth"-Fehler ist der verräterische Hinweis. Ebenso cf-ray, x-amzn-waf, akamai. Das sind Infrastruktur, nicht die API.
Bekannte Signaturen
| Symptom | Tatsächliche Ursache | Fix |
|---|---|---|
403 + Body error code: 1010, server: cloudflare | Cloudflare hat die Client-Signatur gesperrt | Senden Sie einen echten Browser-User-Agent |
Gleicher Fehler für jeden Pfad inkl. / | Edge/WAF-Block oder IP-Sperre | Ändern Sie UA, dann IP/Proxy |
402 | Tatsächlich kein Guthaben mehr: Die Anfrage wurde authentifiziert | Aufladen; der Schlüssel ist in Ordnung |
429 direkt nach einem Erfolg | Echte Ratenbegrenzung | Anfragen verlangsamen, Backoff hinzufügen |
400 mit einer Feldmeldung | Sie haben die API erreicht und die Auth wurde akzeptiert | Korrigieren Sie die Nutzlast; das sind gute Nachrichten |
Ein Validierungsfehler mit 400 ist ein Erfolgssignal für die Triage: Er beweist, dass die Authentifizierung akzeptiert wurde.
Standard-Header für jeden serverseitigen API-Aufruf
Python's urllib sendet User-Agent: Python-urllib/3.x, was viele WAFs sofort sperren. Setzen Sie immer:
headers = {
"User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) "
"AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0 Safari/537.36",
"Accept": "application/json",
"Content-Type": "application/json",
}
Messen Sie dann die Kosten vor jeder Massenabfrage
Sobald es funktioniert, schätzen Sie die Ausgaben nicht. Lesen Sie die Nutzung vor und nach einem Aufruf und lesen Sie das eigene Abrechnungsfeld des Anbieters in der Antwort.
before = usage(); result = call(); after = usage()
print("berechnet:", result.get("billing"), "| gemessen:", before - after)
Was Sie melden sollten
Geben Sie an, was Sie getestet haben und was noch unbekannt ist. "Beide Schlüssel 403" ist kein Befund, wenn ein leerer Schlüssel den gleichen 403 zurückgibt. Sagen Sie stattdessen: "403 ist hier nicht aussagekräftig, ein Null-Schlüssel gibt ihn auch zurück; die Ursache liegt vorgelagert zur Authentifizierung."