A la lliçó anterior vam anar deixant números pel camí: 201 en crear amb Location, 204 sense cos, 404 davant de 410, 409 quan la transició no és possible, 415 quan el Content-Type no s'admet. Cadascun d'aquests codis és una decisió de contracte: és el primer que llegeix un client i el que determina si reintenta, si mostra un error a l'usuari, si redirigeix o si tanca la sessió. Triar malament el codi converteix en indesxifrable una API que per la resta està ben dissenyada. Aquesta lliçó recorre els codis que una API REST fa servir de debò —no la llista completa del registre d'IANA—, construeix un arbre de decisió per encertar-la sempre, i dissenya el cos de l'error de la Botiga Aroma, comparant-lo amb l'estàndard application/problem+json.

1. Les cinc famílies i per què importen
2. La família 2xx: èxit
3. La família 3xx: redirecció
4. La família 4xx: error del client
5. La família 5xx: error del servidor
6. Taula mestra de la Botiga Aroma
7. Arbre de decisió: com triar el codi correcte
8. El cos de l'error: problem+json i el format de la Botiga Aroma
9. Catàleg de codis d'error de negoci
10. Antipatrons

A 01-03 vam veure el mapa; ara entrem en el detall. La primera xifra del codi classifica la resposta:

Aquesta classificació no és decorativa: és lògica de la qual depèn programari real. Un client HTTP genèric, un balancejador o la passarel·la d'un soci decideixen basant-se només en la primera xifra. Si retornes 200 per a un error, cap reintent automàtic no es dispararà i cap alerta no saltarà. Si retornes 500 per una dada mal escrita pel client, el sistema reintentarà una petició que mai no funcionarà, i el teu equip de guàrdia rebrà un avís a les tres de la matinada per una fallada que no és seva.

De la família 1xx només mereix menció 100 Continue, que gestionen els clients HTTP de manera transparent en pujar cossos grans. No la faràs servir explícitament.

L'èxit genèric, amb cos. El fan servir GET, PUT, PATCH correctes i els POST d'acció que no creen cap recurs nou.

Recorda de 02-03: un GET de col·lecció sense resultats és 200 amb {"dades": [], "total": 0}, mai 404.

S'ha creat un recurs. Obligatòria la capçalera Location amb la seva URI.

Location és el que permet al client encadenar sense construir URLs a mà, i és el mínim d'hipermèdia que tota API hauria de complir. A la Botiga Aroma la retornen POST /comandes, POST /cafes, POST /cafes/{id}/ressenyes, POST /comandes/{id}/pagament i tots els subrecursos d'acció.

"He acceptat la petició, però encara no l'he processada." És el codi del processament asíncron, i el seu contracte inclou dir al client on consultar el progrés.

Compte amb el parany del 202: quan retornes 202 estàs dient que pot fallar després, així que necessites un recurs on el client vegi el resultat final. Un 202 sense lloc on mirar és un forat negre.

Èxit sense cos. El client no ha d'intentar parsejar res. Usos a la Botiga Aroma: DELETE correcte, PUT/PATCH quan el client no necessita la representació, i OPTIONS.

Regla estricta: 204 significa cos de longitud zero. Retornar 204 amb un JSON a dins trenca clients que, correctament, ni llegeixen el flux.

Resposta parcial a una petició amb Range. A la Botiga Aroma apareix exactament en un lloc: la descàrrega represa de la factura en PDF.

No es fa servir per paginar JSON: per a això hi ha els mecanismes de 02-06.

El recurs ha canviat d'URI per sempre. La Botiga Aroma ho fa servir per normalitzar la barra final (/cafes/ → /cafes) i per a les URIs heretades de l'API antiga.

"Allò que tens a la memòria cau encara val." Respon a peticions condicionals amb If-None-Match o If-Modified-Since, i va sense cos, que és justament l'estalvi.

La memòria cau condicional completa —ETags, Last-Modified, validació, revalidació— es desenvolupa a 04-06. Aquí n'hi ha prou de saber que 304 no és un error, sinó un èxit molt barat.

El problema històric: davant d'un 301 o 302, molts clients convertien un POST en un GET en seguir la redirecció, cosa que l'estàndard no pretenia però que es va consolidar com a pràctica. Per eliminar l'ambigüitat es van crear dos codis que garanteixen que el mètode i el cos es conserven:

Decisió de la Botiga Aroma: no es fa servir 302 en cap cas. Per al que és permanent, 301 si només afecta lectures i 308 si pot afectar escriptures; per al que és temporal, 307.

És la família més rica i la que més s'equivoca. En totes elles el cos porta el format d'error de la secció 8.

La petició està mal formada o les dades no són vàlides: JSON amb error de sintaxi, tipus incorrecte, camp obligatori absent, camp desconegut (recorda: la Botiga Aroma és estricta a l'entrada), paràmetre de query invàlid.

Nota de disseny important: es retornen tots els errors de validació alhora, no el primer. Un formulari que falla camp a camp, en peticions successives, és una tortura per a l'usuari.

La distinció que més s'equivoca del món HTTP. La manera de recordar-la:

• 401 = "no sé qui ets". Falta l'Authorization, el token és invàlid o ha caducat. La resposta ha d'incloure WWW-Authenticate. El client ho pot arreglar autenticant-se.
• 403 = "sé qui ets i no pots". La identitat és vàlida, però li falten permisos. Tornar-se a autenticar no serveix de res.

El nom 401 Unauthorized és un error històric de l'estàndard: s'hauria de dir Unauthenticated. Conseqüència pràctica a la SPA de la Botiga Aroma: davant d'un 401 intenta refrescar el token i reintentar una vegada; davant d'un 403 mostra directament "no tens permís" i no reintenta.

Existeix un tercer cas, incòmode però important: quan un client autenticat demana un recurs aliè (GET /v1/comandes/com_9999, que és d'una altra persona), respondre 403 confirma que aquesta comanda existeix. Per evitar aquesta fuita, la Botiga Aroma respon 404 als recursos privats d'altres clients. És una decisió de seguretat deliberada, es diu emmascarament i es tracta a 04-02.

410 és més informatiu quan ho saps amb certesa: diu al client que deixi de demanar-ho. És especialment útil en l'apagada de versions antigues (02-07).

El recurs existeix, però no admet aquest mètode. Obligatòria la capçalera Allow.

Distingeix-lo del 404: si DELETE /v1/cafes donés 404, el desenvolupador buscaria una errada a la URL en comptes d'adonar-se que el mètode és l'equivocat.

Es confonen perquè totes dues parlen de formats, però apunten en direccions oposades:

• 406 → el servidor no pot produir el que el client demana a Accept (sortida).
• 415 → el servidor no entén el que el client envia a Content-Type (entrada).

La petició és vàlida però xoca amb l'estat actual del recurs. És el codi de la lògica de negoci, i a la Botiga Aroma apareix sovint:

Altres conflictes del catàleg: comanda_ja_pagada, comanda_ja_anullada, ressenya_ja_moderada, operacio_en_curs. La regla per distingir-lo del 400: si les dades són correctes i el que impedeix l'operació és l'estat del recurs, és 409.

Ha fallat una condició prèvia enviada pel client, típicament If-Match amb un ETag antic. És el mecanisme de concurrència optimista que evita l'actualització perduda:

Els ETags i les peticions condicionals es desenvolupen a 04-06.

422 (reanomenat Unprocessable Content a la RFC 9110) significa: la sintaxi és correcta, entenc el document, però els seus continguts no es poden processar. Exemple canònic: un JSON perfectament format que demana una data de lliurament al passat.

El debat fa anys que és obert i aquestes són les dues postures:

Decisió de la Botiga Aroma: 400 per a tots els errors de validació d'entrada (sintaxi, tipus, camps obligatoris, enumerats, rangs), amb el detall camp a camp a detalls. 422 es reserva per a un cas molt concret i ben delimitat: la reutilització indeguda d'una Idempotency-Key amb un cos diferent (02-03), on la petició és impecable però no es pot processar per un motiu que no és ni de format ni d'estat del recurs.

L'important no és quina de les dues postures tries, sinó escriure-la a la guia d'estil i no desviar-te'n: el que trenca els clients és que el mateix tipus de fallada retorni 400 en un endpoint i 422 en un altre.

S'ha superat el límit de peticions. Ha d'anar acompanyat de Retry-After i, a la Botiga Aroma, de les capçaleres de quota:

Les polítiques, finestres i algorismes de limitació són la lliçó 04-04.

Aquí el client no ha fet res malament. Regla d'or: mai no filtris detalls interns —traces de pila, consultes SQL, rutes de fitxer, noms de servidors— perquè són informació d'or per a un atacant.

El calaix de sastre: excepció no controlada. Ha de portar un identificador de traça perquè el client el pugui citar en obrir una incidència:

Aquest tracaId és la costura entre la resposta i els teus logs, i és la base de l'observabilitat (04-07).

503 és l'únic que es pot planificar, i per això porta Retry-After, que admet segons o una data HTTP:

Precaució amb el 504: el temps d'espera s'ha esgotat, però l'operació pot haver-se executat igualment aigües amunt. És exactament l'escenari que justifica les claus d'idempotència de 02-03.

Recorre aquest arbre per a cada endpoint nou i tindràs mitja documentació escrita.

El codi d'estat diu quina categoria de fallada s'ha produït; el cos diu què ha passat exactament. Sense cos, un 400 obliga el desenvolupador a endevinar.

Existeix un format estàndard de cos d'error, definit originalment a la RFC 7807 i actualitzat per la RFC 9457:

Camps definits per la norma:

Avantatges: és estàndard, hi ha biblioteques que el generen i el consumeixen, i el type com a URI garanteix unicitat global. Inconvenients pràctics: els noms són críptics per a qui no coneix la RFC, type com a URL convida a inventar URLs que ningú no manté, les extensions al mateix nivell que els camps estàndard poden col·lidir, i el Content-Type diferent obliga els clients a gestionar dos tipus de resposta.

Decisió de la Botiga Aroma: format propi, per tres raons: (1) l'embolcall error fa impossible confondre una resposta correcta amb una d'errònia, fins i tot ignorant el codi d'estat; (2) detalls com a array resol de manera natural la validació de formularis, que és el cas més freqüent; (3) mantenir application/json a tota l'API simplifica els clients. La decisió es documenta explícitament al costat de l'alternativa estàndard, i a 02-08 quedarà reflectida com a esquema reutilitzable a OpenAPI.

1. codi és contracte. En snake_case, estable, únic, i mai no es tradueix. És el que el programari compara.
2. missatge és per a humans. Pot canviar de redacció i es pot traduir (Accept-Language, 02-05). Mai el comparis al codi.
3. detalls és un array, sempre present encara que estigui buit, perquè els clients no hagin de comprovar si existeix.
4. Res de dades sensibles: ni consultes, ni traces de pila, ni si un correu existeix a la base de dades.
5. Els 5xx porten tracaId; els 4xx no el necessiten.

La implementació de tot això com a middleware d'Express és la lliçó 03-07; aquí només hem fixat el contracte.

El catàleg forma part del contracte tant com les URIs. Aquest és l'inicial de la Botiga Aroma:

Convenció de noms: <entitat>_<problema> per al que és específic (cafe_no_trobat) i <problema> a seques per al que és transversal (dades_invalides). El catàleg només creix: retirar un codi és un canvi trencador (02-07).

És l'antipatró més estès i el més nociu. Conseqüències: els clients HTTP no detecten l'error, els reintents automàtics no es disparen, el monitoratge marca 100 % d'èxit, els proxys posen l'error a la memòria cau com si fos una resposta bona, i cada consumidor s'ha d'inventar la seva pròpia lògica de detecció. Renuncia del tot al nivell 2 de Richardson.

Si un POST /v1/cafes amb preuEuros: "gratis" provoca un 500, el sistema del client reintentarà una petició condemnada al fracàs i el teu equip rebrà una alerta per una fallada aliena. Regla: si la petició no pot funcionar tal com està, és 4xx.

299 Gairebé OK, 450 Error de negoci, 600 Fallada. Els intermediaris interpreten els codis desconeguts per la seva primera xifra en el millor dels casos, i els rebutgen en el pitjor. Fes servir només codis registrats; per al detall de negoci ja tens el camp codi del cos.

• 404 per a tot error del client, amagant 400, 403 i 409 sota el mateix número.
• 401 quan falten permisos: envia l'usuari a autenticar-se una altra vegada, no serveix de res i sovint provoca bucles de refresc de token.
• Missatges inútils: "Error", "Alguna cosa ha fallat", "Consulta el log".
• Filtrar la traça de pila en producció.
• Cos en un 204: hi ha clients que no llegeixen el flux i el deixaran a mitges.

• Confondre 401 i 403. No sé qui ets davant de sé qui ets i no pots. Memoritza-ho així.
• Oblidar Location en un 201. El client es queda sense la URI del recurs creat.
• Oblidar Allow en un 405 o WWW-Authenticate en un 401: són obligatòries per norma i hi ha clients que en depenen.
• Fer servir 409 per a errors de validació. 409 és de l'estat del recurs; les dades dolentes són 400.
• Retornar 200 amb llista buida… en un element. La col·lecció buida és 200; l'element inexistent és 404.
• Canviar el codi d'un endpoint ja publicat. Passar de 200 a 204 trenca clients que llegeixen el cos: és un canvi trencador (02-07).
• Consell: escriu la taula de codis de cada endpoint abans d'implementar-lo. És una columna obligatòria de la documentació de referència (02-08).
• Consell: comprova els teus errors amb curl -i. Veure la resposta crua descobreix Content-Type mal posats i cossos buits que un client elegant t'amaga.

Indica el codi d'estat, el codi d'error i les capçaleres rellevants de cada situació:

1. POST /v1/cafes sense capçalera Authorization.
2. POST /v1/ressenyes/res_101/aprovacio amb el token d'un client normal.
3. POST /v1/comandes amb 100 unitats de caf_002, que té estoc 80.
4. GET /v1/cafes/caf_999.
5. PUT /v1/comandes/com_5001 (la Botiga Aroma només admet PATCH allà).
6. POST /v1/comandes/com_5001/pagament sobre una comanda ja pagada.
7. PATCH /v1/cafes/caf_001 amb Content-Type: application/xml.
8. POST /v1/cafes amb {"nom": "", "preuEuros": -3}.
9. DELETE /v1/cistelles/cis_77/linies/caf_002, correcte.
10. El servei intern d'estoc no respon en 5 segons.

Una API heretada respon així. Reescriu cada resposta amb el codi, les capçaleres i el cos correctes segons el contracte de la Botiga Aroma.

Tradueix aquest error de la Botiga Aroma al format application/problem+json de la RFC 9457, i explica què s'hi guanya i què s'hi perd en la traducció:

Solució 1

Solució 2

Aquí hi havia dues fallades: el codi (un error de validació és del client, 400, no 500) i la fuita de la traça de pila amb rutes internes del servidor.

El missatge "has d'iniciar sessió" delata que el problema és d'autenticació, així que el codi correcte és 401, no 403, i falta la capçalera WWW-Authenticate.

Solució 3

S'hi guanya: un format estàndard que eines i biblioteques reconeixen sense configuració; un type com a URI globalment única que a més pot ser un enllaç a la documentació de l'error; i instance, que identifica l'ocurrència concreta i ajuda a correlacionar amb els logs.

S'hi perd: l'embolcall error, que permetia distingir d'un cop d'ull una resposta correcta d'una d'errònia sense mirar el codi; l'homogeneïtat del Content-Type a tota l'API; i la nitidesa dels noms —codi/missatge/detalls són més directes per al consumidor que type/title/detail—. A més, la llista d'errors de validació (errors) és una extensió pròpia en tots dos casos: la RFC no l'estandarditza, així que aquesta part s'ha de documentar igualment.

Els codis d'estat són la primera línia del contracte: diuen si l'operació ha anat bé, de qui és el problema i si té sentit reintentar. Ara saps quan retornar 201 amb Location i quan 204 sense cos, distingir 401 de 403 i 404 de 410, reservar 409 per als conflictes d'estat com l'estoc_insuficient, no confondre 406 amb 415, i acompanyar els 5xx de Retry-After i d'un tracaId sense filtrar res intern. Tens a més un arbre de decisió reutilitzable, el catàleg de codis d'error de negoci de la Botiga Aroma i una postura raonada davant d'application/problem+json. I saps què no cal fer: 200 amb exit: false, 500 per dades mal escrites pel client i codis inventats.

Fins aquí hem dissenyat el sobre: on va la petició, amb quin verb i amb quin resultat. Falta el contingut. A la lliçó següent, 02-05 Representacions, capçaleres i negociació de contingut, dissenyarem el cos de les respostes de la Botiga Aroma: noms i tipus de camp, dates, imports monetaris, nuls davant d'absents, l'embolcall dades/total, quan incrustar i quan enllaçar amb _links, l'expansió i la selecció de camps, i tota la negociació de contingut amb Accept, Content-Type, Accept-Language i Accept-Encoding, inclosa la factura en PDF i la pujada d'imatges de cafè.