Coduri de status: 400, 409, 500 și ceilalți
Ai folosit deja 200 și 404. Un API bun are însă un vocabular mai bogat: „datele trimise sunt greșite” (400), „operația intră în conflict cu starea actuală” (409), „ceva s-a stricat pe server” (500). În lecția aceasta afli ce cod se folosește în fiecare situație și cum îl întorci cu metodele din Results.
Codurile pe care le vei folosi zilnic
| Cod | Nume | Când îl folosești | În Results |
|---|---|---|---|
| 200 | OK | cererea a reușit și întorci date | Results.Ok(x) |
| 201 | Created | ai creat o resursă nouă (POST) | Results.Created(...) |
| 204 | No Content | a reușit, dar nu ai nimic de trimis (DELETE) | Results.NoContent() |
| 400 | Bad Request | datele trimise sunt greșite sau incomplete | Results.BadRequest(x) |
| 401 | Unauthorized | clientul nu s-a autentificat | Results.Unauthorized() |
| 403 | Forbidden | e autentificat, dar nu are voie | Results.Forbid() |
| 404 | Not Found | resursa nu există | Results.NotFound(x) |
| 409 | Conflict | cererea e corectă, dar intră în conflict cu starea actuală | Results.Conflict(x) |
| 422 | Unprocessable Entity | datele au formatul bun, dar încalcă o regulă de business | Results.UnprocessableEntity(x) |
| 500 | Internal Server Error | excepție neprinsă în codul serverului | apare singur |
Nu trebuie să le memorezi pe toate acum. 201 și 204 le folosești în lecțiile despre POST și DELETE, iar 401 și 403 în modulul de securitate. Azi lucrezi cu 400 și 409.
400 Bad Request: clientul a trimis ceva greșit
Ai văzut deja 400 produs automat de ASP.NET Core, când un parametru lipsea sau nu se putea converti. Poți întoarce și tu 400 când datele sunt corecte ca tip, dar nu au sens pentru aplicația ta:
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
app.MapGet("/rate/{suma:decimal}/{luni:int}", (decimal suma, int luni) =>
{
if (luni < 1 || luni > 36)
{
return Results.BadRequest("Numărul de rate trebuie să fie între 1 și 36");
}
return Results.Ok(suma / luni);
});
app.Run();
// GET /rate/1200/12
// GET /rate/1200/48GET /rate/1200/12 → 200 OK 100 GET /rate/1200/48 → 400 Bad Request "Numărul de rate trebuie să fie între 1 și 36"
Ca la NotFound, Results.BadRequest("...") trimite mesajul ca string JSON, între ghilimele. Mesajul spune clientului ce să corecteze, nu doar că a greșit.
409 Conflict și 422: regulile aplicației
409 Conflict înseamnă: cererea e bine formulată, dar nu se poate executa din cauza stării actuale a datelor. Exemple: comanzi mai multe bucăți decât sunt în stoc, încerci să creezi un cont cu un email deja folosit, rezervi un loc deja ocupat.
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
var stoc = 5;
app.MapGet("/comanda/{cantitate:int}", (int cantitate) =>
cantitate > stoc
? Results.Conflict($"Stoc insuficient: mai avem doar {stoc} bucăți")
: Results.Ok($"Comandă acceptată: {cantitate} bucăți"));
app.Run();
// GET /comanda/2
// GET /comanda/8GET /comanda/2 → 200 OK "Comandă acceptată: 2 bucăți" GET /comanda/8 → 409 Conflict "Stoc insuficient: mai avem doar 5 bucăți"
422 Unprocessable Entity este o rudă apropiată a lui 400: unele echipe îl folosesc când JSON-ul e corect, dar încalcă o regulă (de exemplu plata a fost refuzată de bancă). Alte echipe folosesc 400 pentru toate. Important este să alegi o regulă în proiect și să o respecți.
Întreabă-te: datele trimise sunt greșite (400)? Resursa cerută nu există (404)? Datele sunt bune, dar starea actuală nu permite operația (409)?
Coduri fără metodă dedicată: StatusCode și Text
Pentru orice alt cod există Results.StatusCode(cod), care trimite doar codul, fără corp. Dacă vrei un cod și un mesaj text simplu (nu JSON), folosește Results.Text(text, statusCode: cod):
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
app.MapGet("/ceai", () => Results.StatusCode(418));
app.MapGet("/abonament", () => Results.Text("Abonamentul a expirat, reînnoiește-l", statusCode: 402));
app.MapGet("/stare", () => Results.Text("Totul funcționează"));
app.Run();
// GET /ceai
// GET /abonament type
// GET /stareGET /ceai → 418 I'm a teapot GET /abonament → 402 Payment Required (text/plain; charset=utf-8) Abonamentul a expirat, reînnoiește-l GET /stare → 200 OK Totul funcționează
- 418 I'm a teapot este o glumă celebră a standardului HTTP (un server-ceainic care refuză să facă cafea); îl poți folosi ca să testezi că StatusCode funcționează;
- 402 Payment Required este rezervat pentru plăți; unele servicii îl folosesc pentru abonamente expirate;
- Results.Text trimite textul cu Content-Type: text/plain, fără ghilimele; fără statusCode codul este 200.
500: când greșește serverul
Codul 500 nu îl întorci de obicei intenționat. Apare singur când codul tău aruncă o excepție pe care nu o prinde nimeni:
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
var produse = new List<string> { "Laptop", "Mouse" };
app.MapGet("/produse/{index:int}", (int index) => produse[index]);
app.Run();
// GET /produse/1
// GET /produse/5GET /produse/1 → 200 OK Mouse GET /produse/5 → 500 Internal Server Error System.ArgumentOutOfRangeException: Index was out of range. Must be non-negative and less than the size of the collection. (Parameter 'index')
produse[5] aruncă ArgumentOutOfRangeException, iar ASP.NET Core răspunde cu 500 Internal Server Error. În Development, corpul conține tipul și mesajul excepției (în aplicația reală pagina de eroare e mai lungă, cu stack trace); în producție clientul primește doar 500. Un 500 este mereu un bug de reparat: aici trebuia verificat indexul și întors 404.
Coduri de status în viața reală
| Situația | Codul potrivit |
|---|---|
| plata a reușit și comanda e salvată | 201 Created |
| cardul a fost refuzat de bancă | 422 Unprocessable Entity (sau 400) |
| produsul din coș nu mai e pe stoc | 409 Conflict |
| emailul de înregistrare nu are @ | 400 Bad Request |
| comanda 98431 nu există | 404 Not Found |
| baza de date nu răspunde | 500 Internal Server Error |
- Greșeală frecventă: să întorci 200 cu {"eroare": "..."}. Clientul vede 200 și crede că a reușit.
- Greșeală frecventă: să întorci 500 pentru date greșite trimise de client. 5xx înseamnă „vina serverului”; datele greșite sunt 4xx.
Construiește două endpoint-uri care aleg codul de status. GET /imparte/{a:int}/{b:int} întoarce 400 cu mesajul Nu se poate împărți la zero dacă b este 0, altfel 200 cu rezultatul a / b. GET /stoc/{cantitate:int} întoarce 409 cu mesajul Stoc insuficient dacă cantitatea este mai mare decât 10, altfel 200 cu textul Rezervat: {cantitate} bucăți. Laboratorul trimite /imparte/10/2, /imparte/1/0, /stoc/3 și /stoc/50.
- În /imparte/{a:int}/{b:int}: dacă b == 0, Results.BadRequest("Nu se poate împărți la zero"), altfel Results.Ok(a / b).
- În /stoc/{cantitate:int}: dacă cantitate > 10, Results.Conflict("Stoc insuficient"), altfel Results.Ok($"Rezervat: {cantitate} bucăți").
- Nu lăsa împărțirea la zero să ajungă la 500.
Soluția exercițiului
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
app.MapGet("/imparte/{a:int}/{b:int}", (int a, int b) =>
b == 0
? Results.BadRequest("Nu se poate împărți la zero")
: Results.Ok(a / b));
app.MapGet("/stoc/{cantitate:int}", (int cantitate) =>
cantitate > 10
? Results.Conflict("Stoc insuficient")
: Results.Ok($"Rezervat: {cantitate} bucăți"));
app.Run(); 