Codurile de status: 2xx, 3xx, 4xx, 5xx
Primul lucru pe care îl citești într-un răspuns este codul de status: trei cifre care spun pe scurt ce s-a întâmplat. În această lecție înveți cele patru familii de coduri, cele mai folosite coduri din practică și le provoci singur în magazinul demo.
Trei cifre, un mesaj
Codul de status este răspunsul scurt al serverului la întrebarea „cum a mers?”. Prima cifră îți spune familia, deci știi imediat dacă e bine sau rău:
| Familia | Înseamnă | Cine a greșit |
|---|---|---|
| 2xx | succes: cererea a reușit | nimeni |
| 3xx | redirecționare: resursa e în altă parte | nimeni, mergi la adresa nouă |
| 4xx | eroare a clientului: cererea e greșită | cel care trimite cererea |
| 5xx | eroare a serverului: serverul n-a reușit | serverul |
Lângă cod, serverul trimite un text scurt, de exemplu 404 Not Found. Textul e doar pentru oameni; programele se uită la număr.
Un 4xx la o cerere greșită este comportamentul corect: serverul te-a oprit. Un 5xx este aproape mereu un bug: serverul a „căzut” în loc să răspundă frumos. Când găsești un 500, ai găsit de obicei ceva de raportat.
Codurile pe care le vei vedea zilnic
| Cod | Text | Când apare în magazin |
|---|---|---|
| 200 | OK | ai cerut lista de produse și ai primit-o |
| 201 | Created | ai adăugat un produs în coș (POST) și s-a creat |
| 204 | No Content | ai scos un produs din coș; succes, dar fără body |
| 301 | Moved Permanently | adresa veche /catalog te trimite la /products |
| 400 | Bad Request | parametru invalid, de exemplu limit=abc |
| 401 | Unauthorized | nu ești autentificat (lipsește tokenul) |
| 403 | Forbidden | ești autentificat, dar nu ai voie (comanda altui client) |
| 404 | Not Found | produsul cu id-ul cerut nu există |
| 405 | Method Not Allowed | metoda nu e permisă pe acea adresă |
| 409 | Conflict | vrei mai multe bucăți decât sunt în stoc |
| 415 | Unsupported Media Type | ai trimis body-ul într-un format pe care serverul nu îl acceptă |
| 422 | Unprocessable Entity | datele au formatul bun, dar sunt invalide (cantitate 0) |
| 429 | Too Many Requests | ai trimis prea multe cereri într-un minut |
| 500 | Internal Server Error | serverul a avut o eroare neprevăzută |
| 503 | Service Unavailable | serverul e oprit temporar (mentenanță, supraîncărcare) |
Nu trebuie să le înveți pe de rost azi. Le vei întâlni pe rând în curs, iar tabelul ăsta rămâne aici ca referință.
4xx: cererea are o problemă
Cel mai cunoscut cod de eroare. Ceri un produs care nu există:
GET https://api.magazin.test/products/9999
404 Not Found
{
"error": "not_found",
"message": "Produsul 9999 nu există."
}Un API bun nu trimite doar codul, ci și un body cu o explicație: error este un cod pentru programe, iar message un text pentru oameni.
401 apare când lipsește autentificarea. Coșul este personal, deci fără token nu îl poți vedea:
GET https://api.magazin.test/cart
401 Unauthorized
{
"error": "unauthorized",
"message": "Lipsește tokenul de autentificare."
}405 apare când metoda nu e permisă. Antetul Allow din răspuns îți spune ce metode poți folosi:
DELETE https://api.magazin.test/products
405 Method Not Allowed
Allow: GET, POST
{
"error": "method_not_allowed",
"message": "Metoda DELETE nu este permisă pe /products."
}401 = „nu știu cine ești” (nu te-ai autentificat). 403 = „știu cine ești, dar nu ai voie”. Le confundă mulți, inclusiv programatori; un tester atent raportează când API-ul folosește codul greșit.
3xx și 5xx
Un 301 spune că resursa s-a mutat. Antetul Location conține adresa nouă. Postman urmează automat redirecționarea, așa că de obicei vezi direct răspunsul final; dacă oprești această opțiune din tabul Settings al cererii (o vei folosi mai târziu în curs), vezi chiar răspunsul 301:
GET https://api.magazin.test/catalog
301 Moved Permanently
Location: https://api.magazin.test/products
{
"message": "Mutat permanent la /products"
}Un 500 înseamnă că serverul s-a „împiedicat”. Magazinul are un endpoint de export care dă mereu eroare, ca să vezi cum arată:
GET https://api.magazin.test/reports/export
500 Internal Server Error
{
"error": "internal_error",
"message": "Exportul a eșuat pe server.",
"requestId": "req_exp4"
}Serverul de ecou îți dă orice cod vrei, la adresa /status/<cod>. E util ca să vezi cum arată un cod în Postman fără să strici nimic:
GET https://echo.test/status/503
503 Service Unavailable
{
"status": 503,
"statusText": "Service Unavailable",
"message": "Ai cerut codul 503."
}Greșeli frecvente
- Te bucuri de orice 2xx. Dacă ai creat ceva cu POST, codul corect e de obicei 201, nu 200. Contează codul exact.
- Crezi că 404 e mereu un bug. Dacă ai cerut un produs care nu există, 404 este răspunsul corect.
- Ignori body-ul erorii. Mesajul din body îți spune adesea exact ce ai greșit.
- Confunzi eroarea de rețea cu un cod de status. „Could not send request” înseamnă că nu a venit niciun răspuns, deci nu există niciun cod.
Din aplicațiile reale
- Pagina „Ups, nu am găsit pagina” de pe un site este un 404 afișat frumos.
- „Sesiunea a expirat, autentifică-te din nou” apare când aplicația primește 401 de la API.
- „Serviciu indisponibil, revino mai târziu” în aplicația băncii, noaptea, la mentenanță, este un 503.
Provoacă intenționat trei erori diferite și citește ce îți spune serverul la fiecare.
- Trimite GET https://api.magazin.test/products/9999 și citește mesajul de 404.
- Trimite DELETE https://api.magazin.test/products și uită-te în antetele răspunsului la Allow.
- Trimite GET https://echo.test/status/503.
Soluția exercițiului
1. GET https://api.magazin.test/products/9999 → 404 Not Found, "Produsul 9999 nu există." 2. DELETE https://api.magazin.test/products → 405 Method Not Allowed, antetul Allow: GET, POST. 3. GET https://echo.test/status/503 → 503 Service Unavailable.
