Konfiguration - REST API
Antworten
| Antwort | Bedeutung |
|---|---|
200 {"success": true} | das Ereignis wurde gespeichert |
200 {"success": false} | das Konto hat sein monatliches Fehlerkontingent aufgebraucht oder dem Body fehlte ein Pflichtfeld - beides sieht von außen gleich aus |
401 {"message": "Unauthenticated."} | die Anfrage trug an keiner der drei Stellen einen Schlüssel |
404 {"message": "Project not found."} | der Schlüssel passt nicht zum Projekt aus der URL, das Projekt ist deaktiviert, oder das Projekt existiert wirklich nicht |
Ein 404 verrät absichtlich nicht, welcher der drei Fälle vorliegt - die Antwort soll nicht offenbaren, ob ein bestimmter Projekt-Token überhaupt existiert.
Fehlergruppierung
Das Panel gruppiert Ereignisse über den Fingerabdruck sha256(Projekt-Token + type + value) und hält eine Zeile pro Fehler und Tag, mit einem Zähler für Vorkommen. Deshalb müssen type und value über Aufrufe desselben Fehlers hinweg stabil bleiben: eine in value eingesetzte Bestellnummer oder Benutzerkennung zerlegt einen Fehler in tausend eigene Zeilen. Lass den variablen Teil im Kontext - der Request-URL, den Benutzerdaten oder den Stack-Frames -, nicht im Meldungstext.
Transaktionsnamen
Das Feld transaction sollte das Routenmuster tragen, etwa GET /orders/{order}, nicht GET /orders/8123. Sonst zerfällt die Transaktionsliste im Panel in so viele Zeilen, wie es konkrete Kennungen gab.
Ratenbegrenzung
Der Ingest erlaubt 1200 Anfragen pro Minute und Projekt-Token (thor.ingest.throttle_per_minute) - ein Sicherheitsventil gegen einen sich verschleifenden Client, kein geschäftliches Kontingent. Es ist unabhängig vom monatlichen Fehlerkontingent: eine Überschreitung endet in einem 429, nicht in einem 200 {"success": false}. Anfragen haben außerdem eine Obergrenze für die Body-Größe, standardmäßig 2 MB.
Daten, die du nicht senden solltest
Anders als die eigenen DockRay-Bibliotheken filtert die REST-API selbst nichts - deine Integration entscheidet, was in request.headers und die user-Felder gelangt. Sende kein Authorization, kein Cookie und keinen anderen Header, der ein Geheimnis trägt. Hänge IP-Adresse, E-Mail oder Benutzernamen nur an, wenn du sie für die Diagnose wirklich brauchst - das sind personenbezogene Daten, keine technischen Metadaten.
Den privaten Schlüssel schützen
Der private Schlüssel ist ein Projektgeheimnis, keine Kennung. Bewahre ihn in Umgebungsvariablen, in einem Secret-Manager oder in der Serverkonfiguration auf - niemals im Repository, in Logs, auf einem Screenshot oder in Code, der an den Browser geht. Ein Projekt kann mehrere Schlüssel haben, deshalb sollten Produktion und Staging je eigene bekommen: jeder lässt sich einzeln widerrufen, ohne die übrigen zu unterbrechen. Der Verdacht, dass ein Schlüssel abgeflossen ist, genügt, um ihn zu widerrufen und einen neuen zu erzeugen.