błędny format żądania

Błędny format żądania to ogólne określenie usterki niezgodności struktury zapytania z wymaganą specyfikacją API.

Struktura żądania a kontrakt interfejsu API

Błędny format żądania oznacza, że zapytanie wysłane do interfejsu API nie ma struktury zgodnej z wymaganiami określonymi przez jego dokumentację. Serwer może oczekiwać danych zapisanych jako JSON, XML, formularz URL-encoded albo multipart/form-data, a otrzymać treść w innym formacie. Problem może dotyczyć również układu obiektów, nazw pól, typów wartości, obowiązkowych parametrów lub sposobu przekazania danych. Sam fakt, że żądanie dociera do serwera, nie oznacza więc, że może zostać poprawnie zinterpretowane.

W przypadku API korzystającego z protokołu HTTP informacja o formacie danych jest często przekazywana w nagłówku Content-Type. Przykładowo application/json wskazuje na dane JSON, natomiast application/x-www-form-urlencoded oznacza parametry zapisane w formie par klucz-wartość. Serwer może także używać nagłówka Accept do określenia oczekiwanego formatu odpowiedzi. Jeżeli klient wyśle poprawny składniowo dokument, ale zadeklaruje niewłaściwy typ zawartości, aplikacja po stronie serwera może odrzucić żądanie albo spróbować odczytać je według niewłaściwych reguł.

Najczęstsze przyczyny odrzucenia danych wejściowych

Jedną z typowych przyczyn jest błąd składniowy w dokumencie JSON. Niepoprawne cudzysłowy, brak przecinka, dodatkowy przecinek na końcu obiektu, niezamknięta tablica albo użycie komentarzy mogą uniemożliwić parserowi odczyt treści. JSON wymaga stosowania podwójnych cudzysłowów wokół nazw właściwości i tekstowych wartości. Nie jest równoważny z zapisem obiektu używanym bezpośrednio w niektórych językach programowania. Błąd może wystąpić także wtedy, gdy klient wysyła zwykły tekst lub dane formularza, mimo że punkt końcowy API oczekuje obiektu JSON.

Format żądania może być odrzucony również z powodów semantycznych. Przykładem jest przekazanie liczby jako tekstu, użycie wartości logicznej w miejsce daty albo umieszczenie pola na niewłaściwym poziomie zagnieżdżenia. Dokument może być formalnie poprawnym JSON-em, lecz nie spełniać schematu wymaganego przez konkretny punkt końcowy. Znaczenie ma także metoda HTTP. Żądanie GET zwykle przekazuje parametry w adresie URL, a dane dla POST lub PUT są często umieszczane w treści żądania. Przesłanie danych w miejscu innym niż przewidziane w specyfikacji może spowodować ich pominięcie lub odrzucenie.

Rozróżnienie błędu formatu od innych odpowiedzi API

W praktyce komunikat o błędnym formacie należy odróżnić od błędu uwierzytelniania, braku uprawnień, nieistniejącego zasobu i awarii serwera. Kod HTTP 400 Bad Request jest ogólną odpowiedzią wskazującą, że serwer uznał żądanie za niepoprawne. Nie przesądza jednak, czy przyczyną był nieprawidłowy JSON, brak parametru, błędny adres, niezgodny schemat czy inna wada danych wejściowych. Niektóre API używają także kodu 422 Unprocessable Content, gdy składnia żądania jest poprawna, ale jego zawartość nie spełnia reguł walidacji. Szczegół przyczyny powinien wynikać z treści odpowiedzi i dokumentacji danego API.

Diagnostykę rozpoczyna się od zapisania pełnego żądania: metody, adresu, parametrów, nagłówków oraz treści. Następnie warto porównać je z przykładem z dokumentacji i sprawdzić, czy klient nie modyfikuje danych przed wysłaniem. Pomocne jest ponowne zakodowanie treści JSON, kontrola kodowania znaków oraz sprawdzenie, czy nagłówek Content-Length odpowiada rzeczywistej długości danych, jeżeli jest ustawiany ręcznie. Nie należy bez potrzeby ujawniać w logach tokenów dostępowych ani pełnych danych logowania. Ważne jest natomiast zachowanie identyfikatora żądania, czasu operacji i kodu odpowiedzi, ponieważ ułatwia to powiązanie błędu po stronie klienta z wpisem w logach serwera.

Sprawdzenie klienta, biblioteki i konfiguracji połączenia

Jeżeli ten sam punkt końcowy działa w jednym programie, a zwraca błąd w innym, przyczyną może być różnica w sposobie serializacji danych. Biblioteka HTTP może automatycznie zamienić obiekt na JSON, ale może też oczekiwać już gotowego łańcucha znaków. Podwójne kodowanie prowadzi wtedy do wysłania tekstu zawierającego JSON zamiast właściwego obiektu. Podobny problem występuje przy ręcznym ustawieniu nagłówka Content-Type bez odpowiedniego zakodowania treści. Warto sprawdzić również wersję klienta, ustawiony adres API, metodę żądania oraz to, czy formularz lub aplikacja nie dołącza pustych pól albo nieaktualnych nazw parametrów.

W komputerze, na którym występuje problem, można porównać żądanie z działającym przykładem z użyciem narzędzi deweloperskich przeglądarki, dziennika aplikacji albo narzędzia testowego obsługującego HTTP. Istotne jest odtworzenie dokładnej kolejności: przygotowanie danych, serializacja, dodanie nagłówków, wysłanie żądania i odczyt odpowiedzi. Jeżeli błąd pojawia się po aktualizacji programu, należy zweryfikować zmianę biblioteki, ustawień formularza lub konfiguracji połączenia. Warszawskie Pogotowie Komputerowe zajmuje się profesjonalną naprawą laptopów i komputerów PC, w tym diagnostyką problemów z aplikacjami, konfiguracją oraz komunikacją programów z usługami sieciowymi.