...
← Curs ASP.NET Core: toate lecțiile
Lecția 12 · Rezultate

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

CodNumeCând îl foloseștiÎn Results
200OKcererea a reușit și întorci dateResults.Ok(x)
201Createdai creat o resursă nouă (POST)Results.Created(...)
204No Contenta reușit, dar nu ai nimic de trimis (DELETE)Results.NoContent()
400Bad Requestdatele trimise sunt greșite sau incompleteResults.BadRequest(x)
401Unauthorizedclientul nu s-a autentificatResults.Unauthorized()
403Forbiddene autentificat, dar nu are voieResults.Forbid()
404Not Foundresursa nu existăResults.NotFound(x)
409Conflictcererea e corectă, dar intră în conflict cu starea actualăResults.Conflict(x)
422Unprocessable Entitydatele au formatul bun, dar încalcă o regulă de businessResults.UnprocessableEntity(x)
500Internal Server Errorexcepție neprinsă în codul serveruluiapare 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/48
GET /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/8
GET /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.

Cum alegi între 400, 404 și 409

Î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 /stare
GET /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/5
GET /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țiaCodul 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 stoc409 Conflict
emailul de înregistrare nu are @400 Bad Request
comanda 98431 nu există404 Not Found
baza de date nu răspunde500 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.
Exercițiul tău

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.
Ambele endpoint-uri pot folosi operatorul ternar: conditie ? Results.X(...) : Results.Ok(...).

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();
Excelent! Continuă cu lecția următoare →
Program.csASP.NET Core
ConsolăSe încarcă...
Mediul de lucru se încarcă. Poți citi lecția între timp.
Rulează codul cu butonul de sus sau cu Ctrl + Enter / Cmd + Enter.
Parcursul tău Primul tău API cu ASP.NET Core Lecția 12 · Coduri de status: 400, 409, 500 și ceilalți
Progres 0% 0 din 22
Lecția curentă 12 / 20 Rezultate