Răspunsul e HTML în loc de JSON (Content-Type: text/html)
Endpointul unui API JSON a întors o pagină HTML (des la erori 404 sau 500), deci clienții nu pot citi eroarea. Dacă URL-ul e corect, e un bug de contract: scrie un test pe Content-Type și raportează-l cu cererea atașată.
Explicat de Tudor Andrei Dumitrescu, Senior Software Developer, fondatorul Academiei ProgramatorilorActualizat la
Ce înseamnă
Un API JSON trebuie să răspundă cu JSON și la erori: clientul (aplicația mobilă, frontend-ul) citește error și message ca să afișeze ceva util. Când un endpoint întoarce o pagină HTML (<html><h1>404 Not Found</h1>...), clientul primește o eroare de parsare și afișează un mesaj generic.
Cauze:
- framework-ul web întoarce pagina lui implicită de eroare, pentru că API-ul nu are un handler JSON pentru 404/500;
- un proxy sau un gateway răspunde înaintea aplicației;
- antetul
Content-Typee setat greșit (text/html), deși body-ul e JSON.
În Postman, problema apare ca JSONError: Unexpected token '<' în teste. Un test pe Content-Type scris înaintea celorlalte o transformă într-un rezultat clar, ușor de raportat.
De ce apare: cauzele frecvente
1Eroare 404 servită ca pagină HTML
GET /products/999 → 404 Content-Type: text/html
<html>...</html>GET /products/999 → 404 Content-Type: application/json
{"error": "not_found", "message": "Produsul 999 nu există."}Formatul erorilor face parte din contractul API-ului.
2Test care parsează fără verificare
const j = pm.response.json();pm.test("Eroarea e JSON", () => pm.expect(pm.response.headers.get("Content-Type")).to.include("application/json"));Testul pe Content-Type arată problema fără eroare de script.
Repară eroarea, direct în pagină
Pe acest mediu, GET {{baseUrl}}/products/999 răspunde 404 cu o pagină HTML în loc de JSON. Adaugă pe cererea „Produs inexistent” un test „Eroarea e JSON” care verifică Content-Type application/json (va pica, arătând problema), trimite cererea, apoi raportează bug-ul: titlul trebuie să spună că eroarea 404 vine ca HTML, cu ultima cerere atașată.
Indiciu
Titlul raportului trebuie să conțină „HTML” și „404”.
Reparația
1. Test pe cerere:
pm.test("Eroarea e JSON", function () {
pm.expect(pm.response.headers.get("Content-Type")).to.include("application/json");
});2. Raport: GET /products/999: eroarea 404 vine ca pagină HTML, nu ca JSON, cu pașii, așteptat (JSON) și obținut (text/html), ultima cerere atașată.
De ce merge
Testul pe Content-Type face problema vizibilă ca test picat, nu ca eroare de script, iar raportul îi spune dezvoltatorului exact ce lipsește: un handler care întoarce erorile în JSON. Serverul a trimis o pagină HTML în loc de JSON, de obicei la o eroare sau o cale greșită. Testul pe tipul conținutului prinde situația clar, înainte ca parsarea să dea un mesaj confuz.
Alte forme ale mesajului
Content-Type: text/html; charset=utf-8 (așteptat application/json)
Cum o eviți pe viitor
- Pune în scriptul colecției un test pe
Content-Typepentru toate răspunsurile API-ului. - Testează și răspunsurile de eroare (404, 422, 500), nu doar succesul.
- Raportează orice răspuns HTML de la un API JSON.
- Adaugă un test pe
Content-Typeînaintea testelor pe body.
Întrebări frecvente
E un bug sau o alegere?
Pentru un API JSON e bug: clienții nu pot interpreta eroarea. Excepție: endpointuri documentate care servesc HTML.
Cum văd pagina primită?
Tabul Body → Preview randează HTML-ul.
Erori înrudite
JSONError: Unexpected token '<' at 1:1 pm.response.json() a încercat să parseze ca JSON un răspuns care începe cu „<”, adică o pagină HTML (o eroare 404/500 a serverului, o pagină de login, un proxy). Uită-te la body în Raw sau Preview și la Content-Type, apoi repară cererea sau verifică statusul înainte să parsezi. AssertionError: expected 'application/json; charset=utf-8' to equal 'application/json' Antetul Content-Type conține și setul de caractere (; charset=utf-8), deci nu e egal cu „application/json”. Verifică doar că include application/json, nu egalitatea exactă. 404 Not Found Serverul nu are resursa sau ruta cerută: calea e scrisă greșit (singular/plural, versiune lipsă), id-ul nu există sau metoda și calea nu se potrivesc. Compară URL-ul final din Console cu documentația și verifică id-ul. Învață Postman de la zero, cu exerciții la fiecare lecție
Curs API Testing cu Postman: lecții scurte, fiecare cu un exercițiu verificat automat, direct în browser. Primele 10 lecții sunt gratuite.
