Konfiguracja - REST API
Na tej stronie Odpowiedzi
Odpowiedzi
| Odpowiedź | Znaczenie |
|---|---|
200 {"success": true} | zdarzenie zostało zapisane |
200 {"success": false} | konto wyczerpało miesięczny limit błędów albo w ciele zabrakło wymaganych pól - obie sytuacje wyglądają z zewnątrz tak samo |
401 {"message": "Unauthenticated."} | w żądaniu nie było klucza w żadnym z trzech miejsc |
404 {"message": "Project not found."} | klucz nie pasuje do projektu z adresu, projekt jest wyłączony, albo projekt naprawdę nie istnieje |
Kod 404 celowo nie mówi, który z trzech powodów zaszedł - odpowiedź nie ma zdradzać, czy dany token projektu w ogóle istnieje.
Grupowanie błędów
Panel grupuje zdarzenia po odcisku sha256(token projektu + type + value) i trzyma jeden wiersz na błąd na dzień, z licznikiem wystąpień. Dlatego type i value muszą być stabilne między wywołaniami tego samego błędu: wklejony do value numer zamówienia albo identyfikator użytkownika rozbija jeden błąd na tysiąc osobnych wierszy. Zmienną część zostaw w kontekście - adresie żądania, danych użytkownika albo ramkach stosu - nie w treści komunikatu.
Nazwy transakcji
Pole transaction powinno nieść wzorzec trasy, na przykład GET /orders/{order}, a nie GET /orders/8123. Inaczej lista transakcji w panelu rozsypuje się na tyle wierszy, ile było konkretnych identyfikatorów.
Limit żądań
Ingest ma limit 1200 żądań na minutę na token projektu (thor.ingest.throttle_per_minute) - to zawór bezpieczeństwa przeciwko zapętlonemu klientowi, nie limit biznesowy. Jest niezależny od miesięcznego limitu błędów: przekroczenie go kończy się odpowiedzią 429, a nie 200 {"success": false}. Żądania mają też sufit rozmiaru ciała, domyślnie 2 MB.
Dane, których nie wysyłać
W przeciwieństwie do oficjalnych bibliotek DockRay, REST API niczego nie filtruje samo - to Twoja integracja decyduje, co trafia w request.headers i w polach user. Nie wysyłaj Authorization, Cookie ani innych nagłówków niosących sekrety. Adres IP, e-mail i nazwę użytkownika dołączaj tylko wtedy, gdy naprawdę są Ci potrzebne w diagnozie - to dane osobowe, a nie techniczne metadane.
Ochrona klucza prywatnego
Klucz prywatny jest sekretem projektu, a nie identyfikatorem. Trzymaj go w zmiennych środowiskowych, w menedżerze sekretów albo w konfiguracji serwera - nigdy w repozytorium, w logach, na zrzucie ekranu ani w kodzie wysyłanym do przeglądarki. Jeden projekt może mieć wiele kluczy, więc produkcja i środowisko testowe powinny dostać osobne: każdy odwołuje się niezależnie, bez przerywania raportowania z pozostałych. Podejrzenie ujawnienia klucza jest wystarczającym powodem, aby go odwołać i wygenerować nowy.