Błędy

Koperta

Wszystkie odpowiedzi błędu mają ten sam kształt JSON:

{ "error": "<code>" }

Status HTTP niesie rodzaj awarii, a pole error — konkretny kod. Nie ma pola message — kody są stabilnymi identyfikatorami maszynowymi, a nie tekstami dla ludzi.

Kody

Kod	Status	Znaczenie
INVALID_KEY	401	Token bearer jest brakujący, źle sformatowany lub nieznany.
RATE_LIMITED	429	Przekroczony limit zapytań na minutę dla Twojego planu. Odpowiedź zawiera też nagłówek Retry-After w sekundach.
QUOTA_EXCEEDED	429	Wykorzystałeś miesięczną kwotę zapytań. Retry-After zawiera liczbę sekund do początku kolejnego miesiąca w strefie CET (00:00 1. dnia w Europe/Warsaw, z uwzględnieniem czasu letniego); nagłówki X-Quota-Limit i X-Quota-Remaining są również ustawione.
INVALID_INPUT	422	Parametr ścieżki lub zapytania nie przeszedł walidacji (np. źle sformatowany kod kraju w /vies/).
MS_UNAVAILABLE	503	Usługa VIES konkretnego Państwa Członkowskiego jest niedostępna. Spróbuj ponownie po krótkiej chwili.
SERVICE_UNAVAILABLE	503	Główna usługa VIES działa z degradacją.
TIMEOUT	503	Wywołanie do usługi nadrzędnej przekroczyło nasz twardy timeout.
no data yet	404	/rates lub /fx zostało zapytane przed pierwszym tickiem crona na świeżym deployu. Powinno być widoczne wyłącznie podczas pierwszego uruchomienia.
snapshot not found	404	Zwracane dla historycznego /rates/YYYY-MM-DD lub /fx/YYYY-MM-DD, dla którego nie istnieje snapshot.

Dwa różne błędy 429

Zarówno RATE_LIMITED, jak i QUOTA_EXCEEDED mają status 429, ale opisują różne tryby awarii:

• RATE_LIMITED — zbyt wiele zapytań w bieżącej minucie. Odczekaj Retry-After sekund i spróbuj ponownie.
• QUOTA_EXCEEDED — wyczerpany miesięczny limit. Retry-After może wynosić dni. Zmień plan na wyższy lub poczekaj do początku kolejnego miesiąca w strefie CET.

Aby je rozróżnić, sprawdzaj pole error, a nie tylko status.

Awarie usług nadrzędnych

VIES jest jedynym endpointem Stawki, który dla każdego zapytania trafia do żywej usługi nadrzędnej. Gdy VIES działa z degradacją, tryb awarii, który zobaczysz, zależy od tego, co zaobserwowaliśmy:

• INVALID_INPUT — kraj lub numer VAT, który przekazałeś, nie przeszedł walidacji po stronie VIES. Popraw dane wejściowe.
• MS_UNAVAILABLE — rejestr podatkowy konkretnego Państwa Członkowskiego jest niedostępny. Spróbuj później; spodziewaj się przerywanych awarii, dopóki ten rejestr się nie podniesie.
• SERVICE_UNAVAILABLE / TIMEOUT — sam VIES jest zdegradowany. Ta sama rekomendacja co przy ponawianiu prób.

Wszystko inne pojawia się jako 502 z ogólnym kodem błędu; takie błędy to nasze bugi lub nieoczekiwane kształty odpowiedzi z usług nadrzędnych. Prosimy o zgłoszenie issue z URL zapytania i znacznikiem czasu.

Czego nie ma w kopercie błędu

• Stack trace.
• Wewnętrznego ID zapytania. (Jest jeden w nagłówkach odpowiedzi jako cf-ray; podawaj go w zgłoszeniach do supportu.)
• Komunikatu przeznaczonego dla użytkownika końcowego. Mapowanie kodów na komunikaty zrób po stronie klienta.