El código de estado dice quién se equivocó
Un código de estado HTTP es el número de tres cifras con el que una API cuenta cómo fue una petición. Las que empiezan por 2 salieron bien, las de 4 fallaron por culpa de quien pidió y las de 5 por culpa del servidor.
Elegir el código correcto y explicar el error ahorra horas a quien usa tu API.
Al terminar esta lección
Nota
Puedo elegir el código de estado de una respuesta y explicar un error con claridad.
Palabras clave
| Palabra | Qué significa | Ejemplo |
|---|---|---|
| Código de estado | el número de tres cifras que dice cómo fue la petición | 404 |
| Error del cliente | un fallo que viene de la petición, del 400 al 499 | |
| Error del servidor | un fallo que viene del servidor, del 500 al 599 | |
| Cuerpo de error | el JSON que explica qué falló | |
| Conflicto | una petición que choca con datos que ya existen | 409 |
Las celdas que rellenan los estudiantes quedan en blanco en esta vista previa.
Los códigos se agrupan por su primera cifra
La primera cifra dice la familia. 2xx: la petición salió bien. 3xx: lo que buscas está en otro sitio. 4xx: el cliente se equivocó. 5xx: falló el servidor.
La cifra importa porque cada familia pide una reacción distinta. Ante un 4xx, quien pide debe corregir la petición. Ante un 5xx, puede esperar y probar otra vez.
Ejemplo resuelto: los códigos que más se usan
| Código | Significa | Ejemplo en la biblioteca |
|---|---|---|
| 200 | Aquí está lo que pedías | Leer la lista de libros |
| 201 | Se creó un recurso | Añadir un libro nuevo |
| 204 | Hecho, sin nada que devolver | Cambiar el estado de un libro |
| 400 | La petición está mal | Un libro sin título |
| 401 | No sabemos quién eres | Pedir un préstamo sin iniciar sesión |
| 403 | Sabemos quién eres, y no puedes | Borrar un libro siendo estudiante |
| 404 | No existe | Pedir una ruta que no existe |
| 409 | Choca con datos existentes | Crear un libro con un id repetido |
| 429 | Demasiadas peticiones | Pedir mil veces por segundo |
| 500 | Falló el servidor | Un fallo del programa de la API |
Las celdas que rellenan los estudiantes quedan en blanco en esta vista previa.
Un error frecuente
Advertencia
Mucha gente cree que un error se puede responder con 200 y explicarlo en el cuerpo. Entonces nadie que mire solo el código se entera. Usa el código de la familia correcta y pon el detalle en el cuerpo del error.
Mira los códigos de la API del laboratorio
Prepara la tabla books y envía peticiones que salen bien y mal. Cada Run imprime solo el código de estado, para que lo compares con la tabla.
Fíjate en un caso sutil. Pedir un libro que no existe, con un filtro, no da 404 en esta API.
Dar a psql la contraseña
export PGPASSWORD=shopSe muestra aquí y no se ejecuta. Crea una cuenta gratuita para pulsar Ejecutar y escribirlo en el terminal de tu propio laboratorio.
Crear la tabla de libros
psql -h db -U shop -q -c "drop table if exists books; create table books (id serial primary key, title text not null, copies int not null default 1, status text not null default 'disponible'); insert into books (title, copies, status) values ('Redes de computadores', 3, 'disponible'), ('Algoritmos y estructuras', 0, 'prestado'), ('Sistemas operativos', 2, 'disponible'), ('Ingenieria del software', 1, 'disponible'); notify pgrst, 'reload schema'"Se muestra aquí y no se ejecuta. Crea una cuenta gratuita para pulsar Ejecutar y escribirlo en el terminal de tu propio laboratorio.
Leer un libro que existe
curl -s -o /dev/null -w "%{http_code}\n" "http://api:3000/books?id=eq.1"Se muestra aquí y no se ejecuta. Crea una cuenta gratuita para pulsar Ejecutar y escribirlo en el terminal de tu propio laboratorio.
Pedir el libro 99, que no existe
curl -s -w "\n" "http://api:3000/books?id=eq.99"Se muestra aquí y no se ejecuta. Crea una cuenta gratuita para pulsar Ejecutar y escribirlo en el terminal de tu propio laboratorio.
Pedir una ruta que no existe
curl -s -o /dev/null -w "%{http_code}\n" "http://api:3000/magazines"Se muestra aquí y no se ejecuta. Crea una cuenta gratuita para pulsar Ejecutar y escribirlo en el terminal de tu propio laboratorio.
Un buen error dice qué falló
El código dice la familia del fallo. El cuerpo de error dice el motivo. Un buen cuerpo lleva un código propio para programas, un mensaje para personas y, si se puede, una pista.
No cuentes secretos en el mensaje: ni la consulta, ni el nombre del servidor interno.
Un libro sin título
curl -s -o /dev/null -w "%{http_code}\n" -X POST -H "Content-Type: application/json" -d '{"copies":1}' "http://api:3000/books"Se muestra aquí y no se ejecuta. Crea una cuenta gratuita para pulsar Ejecutar y escribirlo en el terminal de tu propio laboratorio.
Sacar solo el campo code del error
curl -s -X POST -H "Content-Type: application/json" -d '{"copies":1}' "http://api:3000/books" | grep -o '"code":"[0-9A-Z]*"'Se muestra aquí y no se ejecuta. Crea una cuenta gratuita para pulsar Ejecutar y escribirlo en el terminal de tu propio laboratorio.
Crear un libro con un id repetido
curl -s -o /dev/null -w "%{http_code}\n" -X POST -H "Content-Type: application/json" -d '{"id":1,"title":"Otro libro"}' "http://api:3000/books"Se muestra aquí y no se ejecuta. Crea una cuenta gratuita para pulsar Ejecutar y escribirlo en el terminal de tu propio laboratorio.