Kody błędów i diagnostyka

Ujednolicona struktura błędów HTTP, katalog kodów i zalecenia dotyczące odporności.

Jeżeli żądanie nie może zostać pomyślnie przetworzone, SmallPict zwraca standardowy kod błędu HTTP wraz z czytelnym obiektem JSON ułatwiającym analizę problemu.

Struktura odpowiedzi błędu JSON

JSON

{  "success": false,  "error": {    "code": "INVALID_IMAGE_PAYLOAD",    "message": "Przesłany plik nie jest prawidłowym obrazem lub jest uszkodzony.",    "details": {      "mime_type": "text/html",      "expected": [        "image/jpeg",        "image/png",        "image/webp",        "image/avif"      ]    }  }}

Wykaz kodów błędów HTTP

Kod	Identyfikator	Przyczyna	Zalecane działanie
`400`	`BAD_REQUEST`	Błędna składnia JSON lub niepoprawne parametry.	Sprawdź składnię formatu JSON i nazwy pól.
`401`	`UNAUTHORIZED`	Brak klucza API lub klucz został unieważniony.	Zweryfikuj poprawność nagłówka `X-API-Key`.
`401`	`TIMESTAMP_DRIFT`	Znacznik czasu różni się o ponad ±300s.	Zsynchronizuj zegar serwera przez NTP.
`401`	`INVALID_SIGNATURE`	Wyliczona sygnatura HMAC-SHA256 jest niezgodna.	Sprawdź sposób generowania ciągu kanonicznego i Secret Key.
`403`	`FORBIDDEN`	Klucz nie posiada uprawnień do danego zasobu.	Dostosuj uprawnienia klucza w panelu.
`404`	`NOT_FOUND`	Wskazane zadanie (`job_id`) lub plik nie istnieje.	Upewnij się, że identyfikator w URL jest poprawny.
`413`	`PAYLOAD_TOO_LARGE`	Plik przekracza maksymalny rozmiar dozwolony w Twoim planie.	Zmniejsz wagę lub rozdzielczość pliku przed wysłaniem.
`415`	`UNSUPPORTED_MEDIA`	Format pliku nie jest obsługiwany przez silnik.	Przesyłaj wyłącznie pliki JPEG, PNG, WebP, AVIF lub SVG.
`422`	`UNPROCESSABLE`	Poprawne rozszerzenie, lecz uszkodzona zawartość.	Upewnij się, że plik nie został obcięty podczas wysyłki.
`429`	`RATE_LIMIT_EXCEEDED`	Zbyt duża liczba żądań na sekundę.	Wdróż ponawianie z algorytmem Exponential Backoff.
`429`	`QUOTA_EXCEEDED`	Wyczerpano miesięczną pulę transformacji.	Zwiększ pakiet subskrypcji w panelu.
`500`	`INTERNAL_ERROR`	Nieoczekiwany błąd w klastrze serwerów.	Ponów żądanie po krótkiej chwili.
`503`	`SERVICE_UNAVAILABLE`	Zaplanowane prace serwisowe lub przeciążenie.	Przełącz się tymczasowo w tryb passthrough.