Błędy i ponowienia

Lumin Shield ↗Otwórz panel ↗

Kody odpowiedzi i bezpieczne ponawianie operacji.

Format błędu

{
  "error": {
    "code": "validation",
    "message": "domain must be a hostname",
    "details": {"field": "domains"}
  }
}

Kieruj logikę integracji na code, nie na tekst message. Dla pól formularza wykorzystaj details.field.

Najczęstsze odpowiedzi

Status	Kod	Działanie
400	bad_json, validation	Popraw format żądania.
401	unauthorized, token_invalid	Sprawdź klucz lub sesję; nie ponawiaj w pętli.
403	forbidden, user_required, plan_restricted	Sprawdź rolę, typ uwierzytelnienia i plan.
404	not_found	Sprawdź ID i organizację. Brak dostępu może celowo wyglądać jak brak zasobu.
409	domain_taken, in_use	Usuń konflikt danych lub zależności.
422	validation, quota_exceeded, target_invalid	Popraw dane, wybór zasobu lub limit planu.
429	rate_limited	Odczekaj; ogranicz częstotliwość żądań.
500 / 502 / 503	internal lub błąd połączenia	Dla odczytów ponów z opóźnieniem.

Ponawianie

Dla GET stosuj ograniczoną liczbę prób z rosnącym opóźnieniem i losowym rozrzutem. Nie ponawiaj automatycznie wszystkich błędów 4xx.

Po timeoutcie POST stan jest niepewny: serwer mógł zapisać operację. Sprawdź istniejące zasoby przed następną próbą. Nie zakładaj obsługi kluczy idempotencji ani webhooków, dopóki nie zostaną opisane w kontrakcie API.

Dane w logach

Zapisuj metodę, ścieżkę bez sekretów, status i kod błędu. Nie zapisuj nagłówka Authorization, tokenów, haseł ani pełnych odpowiedzi tworzenia kluczy.