Błędy

Błędy mają wspólną kopertę (zobacz przegląd). Rozgałęziaj logikę według code, loguj meta.request_id i traktuj message jako angielski tekst dla ludzi.

Błędy klienta

Kod	Status	Znaczenie i co zrobić
validation_failed	400	Pole nie przeszło walidacji. field wskazuje pole, details wyjaśnia. Popraw pole.
bad_request	400	Żądania w ogóle nie dało się odczytać: błędny JSON, uszkodzony strumień Content-Encoding, przerwana treść. Nie ma pola do poprawienia; sprawdź transport.
validation_error	400	X-Account-Id wysłano do endpointu, który go zabrania (/auth/login, /auth/refresh, /auth/swap-company, /auth/logout).
cursor_expired	400	Kursor paginacji jest starszy niż 24 godziny. Zacznij listowanie od nowa.
unauthenticated	401	Brak tokenu lub token nieprawidłowy. Odśwież sesję lub sprawdź klucz.
invalid_signature	401	Podpis webhooka nie przeszedł weryfikacji. Zobacz Webhooki.
forbidden	403	Token jest prawidłowy, ale brakuje mu uprawnienia.
account_context_mismatch	403	X-Account-Id nie zgadza się z kontem tokenu. Klient ma nieaktualną informację o bieżącej firmie; odczytaj ją ponownie z sesji.
not_found	404	Zasób nie istnieje albo należy do innego konta lub strony. API nigdy nie rozróżnia tych przypadków.
conflict	409	Konflikt stanu: blokada optymistyczna, ograniczenie unikalności albo czynność niedozwolona w bieżącym stanie (na przykład zapis do scalonej rozmowy).
idempotency_key_conflict	409	Idempotency-Key użyto ponownie z inną treścią.
payload_too_large	413	Treść przekracza limit dla tej rodziny endpointów.
unsupported_media_type	415	Nieprawidłowy Content-Type.
unprocessable	422	Poprawny JSON, ale odrzucony przez regułę biznesową (na przykład termin rezerwacji poza godzinami pracy).
storage_quota_exceeded	422	Konto osiągnęło limit przestrzeni dyskowej swojego planu. details zawiera used_bytes, quota_bytes i requested_bytes; zwolnij miejsce lub zmień plan na wyższy.
rate_limited	429	Zwolnij. Respektuj Retry-After i details.retry_after_seconds.

Błędy serwera

Kod	Status	Znaczenie i co zrobić
internal_error	500	Nieoczekiwana awaria. Ponów raz, a potem skontaktuj się ze wsparciem, podając request_id.
upstream_unavailable	502	Brama w ogóle nie mogła połączyć się z usługą. Krótkie ponowienie zwykle się udaje.
service_unavailable	503	Planowana konserwacja lub otwarty bezpiecznik (circuit breaker). Ponów po czasie z nagłówka Retry-After.
ai_vendor_out_of_funds	503	Twój dostawca AI odrzucił wywołanie z powodów rozliczeniowych (402 lub 429 limitu od dostawcy). Doładuj konto u dostawcy; ponowienie nie pomoże.
upstream_timeout	504	Usługa nie odpowiedziała na czas. Ponów, jeśli obecne jest retry_after.

Ponawianie

Ponawiaj 429, 502, 503, 504 i awarie sieci z wykładniczym wydłużaniem odstępów i wysyłaj przy ponowieniu ten sam Idempotency-Key, aby zapis nigdy nie został wykonany dwa razy. Nie ponawiaj 4xx innych niż 429.