Las cinco categorías
Los códigos HTTP se agrupan por la primera cifra. 1xx son informativos (raros en la práctica). 2xx indican éxito. 3xx son redirecciones. 4xx son errores del cliente: el request está mal o el recurso no existe. 5xx son errores del servidor: el cliente hizo todo bien pero algo falló del otro lado.
2xx: éxito con matices
200 OK es el "todo bien" general. 201 Created se usa
después de crear un recurso (POST exitoso) y debería incluir un header Location
apuntando al recurso nuevo. 202 Accepted indica que el request fue recibido
pero se procesará async. 204 No Content es la respuesta correcta cuando no
hay body (típico en DELETE o PUT exitosos sin retorno).
3xx: redirecciones
301 Moved Permanently indica que el recurso cambió de URL para siempre; los buscadores actualizan el índice. 302 Found y 307 Temporary Redirect son redirecciones temporales (la diferencia: 307 obliga a mantener el método HTTP). 304 Not Modified se devuelve cuando el cliente tiene una copia válida en caché y no hace falta retransmitir.
4xx: errores del cliente
Los más comunes: 400 Bad Request (request mal formado), 401 Unauthorized (faltan credenciales o son inválidas), 403 Forbidden (autenticado pero sin permiso), 404 Not Found (recurso inexistente), 409 Conflict (estado actual incompatible con el request, típico en concurrencia), 422 Unprocessable Entity (validación de campos), 429 Too Many Requests (rate limit excedido).
5xx: errores del servidor
500 Internal Server Error es el catch-all: algo falló y no es culpa del
cliente. 502 Bad Gateway indica que un upstream devolvió error.
503 Service Unavailable es mantenimiento o sobrecarga (mandá
Retry-After). 504 Gateway Timeout: el upstream no respondió
a tiempo.
401 vs 403: el clásico
La distinción es: 401 = "no sé quién sos"; 403 = "sé quién sos pero no podés". Si el
usuario está logueado y trata de acceder al panel admin sin ser admin, devolvé 403. Si el
token expiró, devolvé 401 con header WWW-Authenticate.
422 vs 400
400 es para syntax errors: JSON inválido, header faltante. 422 (semantic) es cuando el JSON parsea bien pero los datos no cumplen reglas: email inválido, edad negativa, campo requerido vacío. Acompañalo con un body que liste los errores por campo.
Idempotencia y retries
GET, PUT y DELETE son idempotentes: repetirlos no cambia el estado. POST no lo es. Esto
importa cuando el cliente reintenta tras un 5xx: con PUT podés repetir sin miedo, con
POST puede crear duplicados. La práctica actual es usar header
Idempotency-Key en POST para garantizar que no se duplique.