Authentifizierung
Ein Header, ein Schlüssel und eine Handvoll Fehler, von denen jeder etwas ganz Bestimmtes bedeutet.
Der Header
Schick deinen Schlüssel bei jeder Anfrage als X-API-Key mit. Es gibt keinen OAuth-Flow, keinen Token-Tausch und nichts, was du erneuern müsstest.
curl -X POST https://api.occultapi.com/api/astro/tithi/ \
-H "X-API-Key: yt_live_a1b2c3d4_x9K2mQ7vB4nR8sL1wY6tZ3pC5hJ0dF" \
-H "Content-Type: application/json" \
-d '{ "date_time": "2026-09-16T06:00:00+05:30", "latitude": 26.9124, "longitude": 75.7873, "timezone_as_float": 5.5 }'Schlüsselformat
Schlüssel sehen so aus: yt_live_a1b2c3d4_x9K2mQ7vB4nR8sL1wY6tZ3pC5hJ0dF – Marke, Umgebung, ein öffentliches Präfix aus acht Zeichen und dann der geheime Teil.
yt_live_…verbraucht echte Credits aus deinem Guthaben.yt_test_…ist für die Entwicklung gedacht und in deinen Nutzungsdaten auch so gekennzeichnet.
Das Präfix ist absichtlich öffentlich und indexiert: Landet ein Schlüssel einmal in einem öffentlichen Repository, lässt er sich allein über das Präfix finden und widerrufen – ohne dass jemand den geheimen Teil kennen muss.
Einmal angezeigt, als Hash gespeichert
Ein Schlüssel wird genau einmal angezeigt: wenn du ihn erstellst. Wir speichern nur einen SHA-256-Hash, sodass weder ein Administrator noch ein Datenbank-Dump ihn wiederherstellen kann. Wir können ihn dir also tatsächlich nicht noch einmal schicken. Danach siehst du nur noch das Präfix und die letzten vier Zeichen – genug, um zwei Schlüssel in einer Liste auseinanderzuhalten.
Schlüssel verloren? Erstell einen neuen und widerruf den alten. Das geht schneller als eine Anfrage bei uns, und mehr könnten wir ohnehin nicht tun.
Fehler – und welche keine Authentifizierungsprobleme sind
Jeder Fehler kommt im Standardformat mit is_error: true und einem stabilen, maschinenlesbaren Code in message. Verzweige anhand des Codes, nicht anhand des Textes.
| Status | message | Bedeutung | Lösung |
|---|---|---|---|
| 401 | invalid_api_key | Der Schlüssel fehlt, ist fehlerhaft, widerrufen oder abgelaufen. | Prüf, ob der Header X-API-Key wirklich bei uns ankommt. Nach einer Rotation den neuen Schlüssel deployen. |
| 402 | insufficient_credits | Der Schlüssel ist gültig, das Guthaben aber leer. | Tarif upgraden oder auf das monatliche Zurücksetzen warten. Das ist kein Authentifizierungsproblem – ein neuer Schlüssel hilft nicht. |
| 403 | endpoint_not_allowed | Diese Route steht API-Schlüsseln nicht zur Verfügung: Pfad oder Methode stimmen nicht, oder der Endpoint wurde abgeschaltet. | Gleich Route und Methode mit der Referenz ab. Weder ein neuer Versuch noch ein neuer Schlüssel hilft. |
| 403 | scope_not_allowed | Dem Schlüssel fehlt der Scope, den dieser Endpoint braucht. | Erstell einen Schlüssel mit den passenden Scopes oder lass die Scopes leer – dann gelten alle. |
| 403 | ip_not_allowed | Der Schlüssel hat eine IP-Allowlist, und die Anfrage kam von einer Adresse, die nicht darauf steht. | Ruf von einer freigegebenen IP aus auf oder erstell einen Schlüssel mit den richtigen IPs – oder ganz ohne, dann ist jede IP erlaubt. |
| 403 | account_suspended | Das Konto ist gesperrt, deshalb wird jeder seiner Schlüssel abgewiesen. | Wende dich an den Support. Ein neuer Schlüssel hilft nicht. |
| 429 | api_key_rate_limited | Zu viele Anfragen mit diesem Schlüssel innerhalb einer Minute. | Kurz pausieren und nach den Sekunden aus dem Header Retry-After erneut versuchen. |
| 400 | (Feldfehler) | Der Anfrage-Body war fehlerhaft. message nennt jedes betroffene Feld. | message lesen – die Meldung ist konkret. Wird nie berechnet. |
Was man nicht oft genug sagen kann: 402 ist kein Authentifizierungsfehler. Der Schlüssel ist in Ordnung, nur das Guthaben ist leer. Einen neuen Schlüssel zu erzeugen ist der typische Fehlgriff und ändert nichts.
Credit-Header
Jede Antwort verrät, was der Aufruf gekostet hat und was noch übrig ist. So verfolgst du deine Ausgaben ohne zweite Anfrage.
X-Credits-Cost: 1 # what this endpoint costs
X-Credits-Charged: 1 # what you were actually billed — 0 on any error
X-Credits-Remaining: 149 # balance after this callLoggen solltest du vor allem X-Credits-Charged. Eine fehlgeschlagene Anfrage meldet dort immer 0: Der Credit wird vor der Berechnung reserviert und wieder freigegeben, wenn sie kein sauberes Ergebnis liefert. Eine fehlerhafte Integration kann so kein Guthaben leerräumen, während du sie debuggst.
Rate-Limits
Die Limits gelten pro Schlüssel und Minute. Sie sollen einen geleakten Schlüssel eindämmen, nicht dich ausbremsen. Überschreitest du ein Limit, bekommst du einen 429 mit dem Header Retry-After in Sekunden – warte so lange, statt sofort neu zu senden. Antworten enthalten außerdem X-RateLimit-Limit und X-RateLimit-Remaining.
Ein 429 wird nie berechnet. Stößt du im normalen Betrieb ans Limit, bitte uns, es anzuheben.
Schlüssel sicher aufbewahren
- Ruf die API von deinem Server auf, nicht aus dem Browser. Ein Schlüssel im Frontend-Bundle oder in einer mobilen App ist öffentlich, egal wie er heißt. Jeder kann ihn auslesen und dein Guthaben verbrauchen.
- Bewahr ihn in einer Umgebungsvariable oder einem Secret-Manager auf. Committe ihn nie.
- Nimm für jede Umgebung einen eigenen Schlüssel. Dann kannst du einen widerrufen, ohne die anderen lahmzulegen.
- Zum Rotieren erstellst du zuerst den neuen Schlüssel, deployst ihn und widerrufst dann den alten. In genau dieser Reihenfolge fällt zwischendurch nichts aus.
- Widerruf einen Schlüssel sofort, wenn er geleakt sein könnte. Der Widerruf wirkt umgehend, dein restliches Guthaben bleibt unberührt.
All das verwaltest du auf deiner Schlüsselseite.