Web y marketing

Referencia de Códigos de Estado HTTP

Busca y aprende el significado, causa típica y uso de cada código de estado HTTP común, con fragmentos en cURL/Python/JS/PHP.

100 Continue #

Respuesta provisional que indica que el servidor ha recibido las cabeceras y el cliente puede enviar el cuerpo. RFC 9110 §15.2.1.

Causa común

El cliente envió Expect: 100-continue para comprobar si el servidor aceptará un cuerpo grande antes de mandarlo.

Cuándo usarlo

Se utiliza entre cabeceras y cuerpo de subidas largas (PUT, POST) para que el cliente no malgaste ancho de banda.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 100 Continue

import requests
r = requests.get("https://example.com/path")
if r.status_code == 100:
    print("Continue")

const r = await fetch("https://example.com/path");
if (r.status === 100) {
  console.log("Continue");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 100);
// or:
http_response_code(100);

101 Switching Protocols #

El servidor acepta cambiar a otro protocolo de aplicación sobre la misma conexión TCP, listado en Upgrade. RFC 9110 §15.2.2.

Causa común

El cliente pidió Upgrade (normalmente WebSocket o HTTP/2 sobre h2c) y el servidor aceptó.

Cuándo usarlo

Handshakes de WebSocket es el caso dominante hoy. Tras 101 la conexión deja de ser HTTP.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 101 Switching Protocols

import requests
r = requests.get("https://example.com/path")
if r.status_code == 101:
    print("Switching Protocols")

const r = await fetch("https://example.com/path");
if (r.status === 101) {
  console.log("Switching Protocols");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 101);
// or:
http_response_code(101);

200 OK #

Respuesta estándar de éxito — la petición se atendió y el cuerpo lleva la representación pedida. RFC 9110 §15.3.1.

Causa común

La petición es válida, autorizada y se completó sin redirigir.

Cuándo usarlo

GETs que devuelven datos, POSTs/PUTs procesados al instante, respuestas sanas de API.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 200 OK

import requests
r = requests.get("https://example.com/path")
if r.status_code == 200:
    print("OK")

const r = await fetch("https://example.com/path");
if (r.status === 200) {
  console.log("OK");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 200);
// or:
http_response_code(200);

201 Created #

La petición tuvo éxito y se creó un recurso nuevo. El header Location DEBERÍA apuntar al recurso creado. RFC 9110 §15.3.2.

Causa común

Un POST o PUT creó un recurso (fila en BD, archivo, usuario, etc.).

Cuándo usarlo

Tras crear recursos REST. Devuelve la representación en el cuerpo y Location en la cabecera.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 201 Created

import requests
r = requests.get("https://example.com/path")
if r.status_code == 201:
    print("Created")

const r = await fetch("https://example.com/path");
if (r.status === 201) {
  console.log("Created");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 201);
// or:
http_response_code(201);

202 Accepted #

La petición se aceptó para procesar pero aún no se ha completado. El procesamiento puede acabar fallando. RFC 9110 §15.3.3.

Causa común

Procesamiento asíncrono encolado. El trabajo se hace después.

Cuándo usarlo

Jobs en segundo plano, importación por lotes, cualquier cosa que devuelva una URL de estado mientras corre.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 202 Accepted

import requests
r = requests.get("https://example.com/path")
if r.status_code == 202:
    print("Accepted")

const r = await fetch("https://example.com/path");
if (r.status === 202) {
  console.log("Accepted");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 202);
// or:
http_response_code(202);

204 No Content #

La petición tuvo éxito; la respuesta no lleva cuerpo a propósito. Las cabeceras pueden traer metadatos. RFC 9110 §15.3.5.

Causa común

Una actualización o borrado que no necesita devolver representación.

Cuándo usarlo

Respuestas DELETE, PUT/PATCH donde el cliente ya tiene la nueva representación, endpoints save-and-stay.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 204 No Content

import requests
r = requests.get("https://example.com/path")
if r.status_code == 204:
    print("No Content")

const r = await fetch("https://example.com/path");
if (r.status === 204) {
  console.log("No Content");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 204);
// or:
http_response_code(204);

206 Partial Content #

El servidor devolvió solo parte de la representación en respuesta a una petición con Range. RFC 9110 §15.3.7.

Causa común

El cliente pidió un rango de bytes con la cabecera Range.

Cuándo usarlo

Descargas reanudables, streaming de vídeo con seek y descargas en trozos paralelos.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 206 Partial Content

import requests
r = requests.get("https://example.com/path")
if r.status_code == 206:
    print("Partial Content")

const r = await fetch("https://example.com/path");
if (r.status === 206) {
  console.log("Partial Content");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 206);
// or:
http_response_code(206);

301 Moved Permanently #

El recurso destino tiene un nuevo URI permanente. Los clientes DEBERÍAN actualizar marcadores y los buscadores el índice. RFC 9110 §15.4.2.

Causa común

Cambio de URL canónica — renombrado de dominio, slug, migración a HTTPS.

Cuándo usarlo

Redirecciones de largo plazo. Evita 301 para redirecciones cortas por la cacheo agresivo.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 301 Moved Permanently

import requests
r = requests.get("https://example.com/path")
if r.status_code == 301:
    print("Moved Permanently")

const r = await fetch("https://example.com/path");
if (r.status === 301) {
  console.log("Moved Permanently");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 301);
// or:
http_response_code(301);

302 Found #

El recurso reside temporalmente en otro URI. Los clientes deberían pedir el nuevo URI sin cambiar el método, pero históricamente reescriben POST a GET. RFC 9110 §15.4.3.

Causa común

Redirección temporal con comportamiento de cambio de método heredado, mantenido por compatibilidad.

Cuándo usarlo

Código legado. En APIs nuevas prefiere 303 o 307 para evitar ambigüedad.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 302 Found

import requests
r = requests.get("https://example.com/path")
if r.status_code == 302:
    print("Found")

const r = await fetch("https://example.com/path");
if (r.status === 302) {
  console.log("Found");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 302);
// or:
http_response_code(302);

303 See Other #

Redirige a un recurso que debe obtenerse con GET, sea cual sea el método original. RFC 9110 §15.4.4.

Causa común

Tras un POST no idempotente, el servidor envía al cliente a una página de confirmación o al recurso recién creado.

Cuándo usarlo

Patrón Post/Redirect/Get. Siempre reescribe a GET, ideal tras enviar un formulario.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 303 See Other

import requests
r = requests.get("https://example.com/path")
if r.status_code == 303:
    print("See Other")

const r = await fetch("https://example.com/path");
if (r.status === 303) {
  console.log("See Other");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 303);
// or:
http_response_code(303);

304 Not Modified #

La representación cacheada por el cliente sigue siendo válida; no se envía cuerpo. RFC 9110 §15.4.5.

Causa común

El cliente envió If-None-Match o If-Modified-Since y los validadores coincidieron con el recurso actual.

Cuándo usarlo

Respuestas condicionales para cacheo. Ahorra ancho de banda en estáticos y APIs sin cambios.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 304 Not Modified

import requests
r = requests.get("https://example.com/path")
if r.status_code == 304:
    print("Not Modified")

const r = await fetch("https://example.com/path");
if (r.status === 304) {
  console.log("Not Modified");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 304);
// or:
http_response_code(304);

307 Temporary Redirect #

Como 302, pero conserva explícitamente método y cuerpo. RFC 9110 §15.4.8.

Causa común

Redirección breve en que el POST/PUT original debe reproducirse en el nuevo URI.

Cuándo usarlo

Redirecciones de mantenimiento, enrutado A/B o geográfico que deben preservar el método.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 307 Temporary Redirect

import requests
r = requests.get("https://example.com/path")
if r.status_code == 307:
    print("Temporary Redirect")

const r = await fetch("https://example.com/path");
if (r.status === 307) {
  console.log("Temporary Redirect");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 307);
// or:
http_response_code(307);

308 Permanent Redirect #

Como 301, pero conserva explícitamente método y cuerpo. RFC 9110 §15.4.9.

Causa común

Cambio canónico de URI para métodos no-GET (upgrade a HTTPS para APIs POST, renombrado de ruta).

Cuándo usarlo

Redirecciones permanentes en APIs REST. Usa en vez de 301 cuando no se debe reescribir el método.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 308 Permanent Redirect

import requests
r = requests.get("https://example.com/path")
if r.status_code == 308:
    print("Permanent Redirect")

const r = await fetch("https://example.com/path");
if (r.status === 308) {
  console.log("Permanent Redirect");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 308);
// or:
http_response_code(308);

400 Bad Request #

El servidor no puede procesar la petición por error del cliente: sintaxis incorrecta, framing inválido, enrutado engañoso. RFC 9110 §15.5.1.

Causa común

JSON roto, campo obligatorio ausente, cabecera mal formada, cookie demasiado grande.

Cuándo usarlo

Error genérico de cliente. Prefiere códigos más específicos (422, 411, 415) cuando apliquen.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 400 Bad Request

import requests
r = requests.get("https://example.com/path")
if r.status_code == 400:
    print("Bad Request")

const r = await fetch("https://example.com/path");
if (r.status === 400) {
  console.log("Bad Request");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 400);
// or:
http_response_code(400);

401 Unauthorized #

La petición carece de credenciales válidas. La respuesta DEBE incluir WWW-Authenticate con los esquemas aceptados. RFC 9110 §15.5.2.

Causa común

Token ausente, expirado o inválido; falta de header Authorization donde se exige.

Cuándo usarlo

Endpoints tras autenticación. Distinto de 403 — 401 es "no autenticado", 403 es "autenticado pero sin permiso".

curl -i -X HEAD https://example.com/path
# HTTP/1.1 401 Unauthorized

import requests
r = requests.get("https://example.com/path")
if r.status_code == 401:
    print("Unauthorized")

const r = await fetch("https://example.com/path");
if (r.status === 401) {
  console.log("Unauthorized");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 401);
// or:
http_response_code(401);

403 Forbidden #

El servidor entendió la petición pero se niega a autorizarla. RFC 9110 §15.5.4.

Causa común

Usuario autenticado sin permiso o recurso bloqueado por IP/región.

Cuándo usarlo

Errores de autorización, listas de IP, control basado en roles.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 403 Forbidden

import requests
r = requests.get("https://example.com/path")
if r.status_code == 403:
    print("Forbidden")

const r = await fetch("https://example.com/path");
if (r.status === 403) {
  console.log("Forbidden");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 403);
// or:
http_response_code(403);

404 Not Found #

El servidor no halla representación actual del recurso. Puede usarse para ocultar un 403. RFC 9110 §15.5.5.

Causa común

URL mal escrita, recurso eliminado o que nunca existió.

Cuándo usarlo

Respuesta por defecto para rutas y recursos ausentes. Se cachea menos agresivamente que 410.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 404 Not Found

import requests
r = requests.get("https://example.com/path")
if r.status_code == 404:
    print("Not Found")

const r = await fetch("https://example.com/path");
if (r.status === 404) {
  console.log("Not Found");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 404);
// or:
http_response_code(404);

405 Method Not Allowed #

El método no se admite en el recurso. La respuesta DEBE incluir Allow con los métodos soportados. RFC 9110 §15.5.6.

Causa común

DELETE en una colección de solo lectura, POST en un recurso singleton, etc.

Cuándo usarlo

APIs REST que quieren ser explícitas sobre los verbos permitidos.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 405 Method Not Allowed

import requests
r = requests.get("https://example.com/path")
if r.status_code == 405:
    print("Method Not Allowed")

const r = await fetch("https://example.com/path");
if (r.status === 405) {
  console.log("Method Not Allowed");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 405);
// or:
http_response_code(405);

406 Not Acceptable #

El servidor no puede producir representación compatible con las cabeceras Accept-*. RFC 9110 §15.5.7.

Causa común

El cliente pidió application/xml pero solo hay application/json.

Cuándo usarlo

Negociación estricta de contenido. Muchas APIs devuelven JSON por defecto en lugar de 406.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 406 Not Acceptable

import requests
r = requests.get("https://example.com/path")
if r.status_code == 406:
    print("Not Acceptable")

const r = await fetch("https://example.com/path");
if (r.status === 406) {
  console.log("Not Acceptable");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 406);
// or:
http_response_code(406);

408 Request Timeout #

El servidor dejó de esperar a que el cliente completara la petición. RFC 9110 §15.5.9.

Causa común

Conexión lenta, subida a medias, keep-alive inactivo más allá del timeout.

Cuándo usarlo

Proxies inversos y balanceadores frente a clientes lentos.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 408 Request Timeout

import requests
r = requests.get("https://example.com/path")
if r.status_code == 408:
    print("Request Timeout")

const r = await fetch("https://example.com/path");
if (r.status === 408) {
  console.log("Request Timeout");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 408);
// or:
http_response_code(408);

409 Conflict #

La petición entra en conflicto con el estado actual del recurso. RFC 9110 §15.5.10.

Causa común

Dos clientes editan el mismo registro a la vez; violación de unicidad; PUT con ETag desfasado.

Cuándo usarlo

Control de concurrencia optimista, creación idempotente.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 409 Conflict

import requests
r = requests.get("https://example.com/path")
if r.status_code == 409:
    print("Conflict")

const r = await fetch("https://example.com/path");
if (r.status === 409) {
  console.log("Conflict");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 409);
// or:
http_response_code(409);

410 Gone #

El recurso se eliminó intencionadamente y no volverá. RFC 9110 §15.5.11.

Causa común

Contenido borrado de forma permanente; endpoint de API descontinuado.

Cuándo usarlo

Páginas retiradas en las que quieres que los crawlers retiren el URL antes que con 404.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 410 Gone

import requests
r = requests.get("https://example.com/path")
if r.status_code == 410:
    print("Gone")

const r = await fetch("https://example.com/path");
if (r.status === 410) {
  console.log("Gone");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 410);
// or:
http_response_code(410);

411 Length Required #

La petición carece de Content-Length cuando el servidor lo exige. RFC 9110 §15.5.12.

Causa común

Cliente en streaming que no buferizó el cuerpo ni usó chunked transfer encoding.

Cuándo usarlo

Servidores que prohíben subidas chunked en ciertos endpoints.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 411 Length Required

import requests
r = requests.get("https://example.com/path")
if r.status_code == 411:
    print("Length Required")

const r = await fetch("https://example.com/path");
if (r.status === 411) {
  console.log("Length Required");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 411);
// or:
http_response_code(411);

413 Content Too Large #

El cuerpo es mayor de lo que el servidor admite. RFC 9110 §15.5.14. Renombrado de "Payload Too Large" en RFC 9110.

Causa común

Subida por encima del límite configurado, archivo más allá del tamaño máximo del formulario.

Cuándo usarlo

Endpoints de subida, APIs JSON con tope de cuerpo.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 413 Content Too Large

import requests
r = requests.get("https://example.com/path")
if r.status_code == 413:
    print("Content Too Large")

const r = await fetch("https://example.com/path");
if (r.status === 413) {
  console.log("Content Too Large");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 413);
// or:
http_response_code(413);

414 URI Too Long #

El URI de la petición es más largo de lo que el servidor admite interpretar. RFC 9110 §15.5.15.

Causa común

Query strings enormes (a menudo de formularios enviados con method=GET) o tokens embebidos en la URL.

Cuándo usarlo

Cuando los usuarios golpean el endpoint con URLs anormalmente largas — pasa el formulario a POST.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 414 URI Too Long

import requests
r = requests.get("https://example.com/path")
if r.status_code == 414:
    print("URI Too Long")

const r = await fetch("https://example.com/path");
if (r.status === 414) {
  console.log("URI Too Long");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 414);
// or:
http_response_code(414);

415 Unsupported Media Type #

El servidor rechaza el cuerpo en el formato descrito por Content-Type. RFC 9110 §15.5.16.

Causa común

Enviar application/xml a un endpoint solo JSON, o Content-Type incorrecto/ausente.

Cuándo usarlo

APIs REST que aceptan estrictamente uno o dos media types.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 415 Unsupported Media Type

import requests
r = requests.get("https://example.com/path")
if r.status_code == 415:
    print("Unsupported Media Type")

const r = await fetch("https://example.com/path");
if (r.status === 415) {
  console.log("Unsupported Media Type");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 415);
// or:
http_response_code(415);

418 I’m a teapot #

Broma de inocentes de la RFC 2324 (HTCPCP). Algunos servidores lo devuelven como error genérico de "me niego". No es status real de producción.

Causa común

Software que devuelve 418 a propósito, en trampas anti-abuso o easter eggs.

Cuándo usarlo

Solo easter eggs. No usar en APIs reales — muchos proxies y clientes no lo reconocen.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 418 I’m a teapot

import requests
r = requests.get("https://example.com/path")
if r.status_code == 418:
    print("I’m a teapot")

const r = await fetch("https://example.com/path");
if (r.status === 418) {
  console.log("I’m a teapot");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 418);
// or:
http_response_code(418);

422 Unprocessable Content #

La sintaxis está bien pero el servidor no puede procesar el contenido semántico. RFC 9110 §15.5.21. Originalmente en WebDAV (RFC 4918).

Causa común

Errores de validación sobre un payload JSON estructuralmente válido — campo obligatorio vacío, valor fuera de rango.

Cuándo usarlo

Validación de formularios en APIs modernas. Más limpio que 400 porque la petición es sintácticamente válida.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 422 Unprocessable Content

import requests
r = requests.get("https://example.com/path")
if r.status_code == 422:
    print("Unprocessable Content")

const r = await fetch("https://example.com/path");
if (r.status === 422) {
  console.log("Unprocessable Content");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 422);
// or:
http_response_code(422);

423 Locked #

El recurso está bloqueado. RFC 4918 (WebDAV).

Causa común

Recurso WebDAV con un lock exclusivo de otro usuario.

Cuándo usarlo

Servidores de colaboración documental, frontends de control de versiones.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 423 Locked

import requests
r = requests.get("https://example.com/path")
if r.status_code == 423:
    print("Locked")

const r = await fetch("https://example.com/path");
if (r.status === 423) {
  console.log("Locked");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 423);
// or:
http_response_code(423);

425 Too Early #

El servidor no quiere procesar una petición que pueda repetirse, normalmente porque viajó en TLS 1.3 0-RTT (early data). RFC 8470.

Causa común

Petición en TLS 1.3 0-RTT que el servidor considera insegura para replay.

Cuándo usarlo

Proteger endpoints no idempotentes frente a replays durante handshakes 0-RTT.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 425 Too Early

import requests
r = requests.get("https://example.com/path")
if r.status_code == 425:
    print("Too Early")

const r = await fetch("https://example.com/path");
if (r.status === 425) {
  console.log("Too Early");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 425);
// or:
http_response_code(425);

428 Precondition Required #

El servidor de origen exige que la petición sea condicional. RFC 6585.

Causa común

El servidor quiere que los clientes usen If-Match / If-Unmodified-Since para evitar conflictos de actualización perdida.

Cuándo usarlo

APIs con bloqueo optimista que rechazan escrituras incondicionales.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 428 Precondition Required

import requests
r = requests.get("https://example.com/path")
if r.status_code == 428:
    print("Precondition Required")

const r = await fetch("https://example.com/path");
if (r.status === 428) {
  console.log("Precondition Required");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 428);
// or:
http_response_code(428);

429 Too Many Requests #

El usuario ha enviado demasiadas peticiones en un intervalo. RFC 6585.

Causa común

Límite de tasa alcanzado; la respuesta suele incluir Retry-After.

Cuándo usarlo

APIs con rate limit, throttling de login, mitigación de abuso.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 429 Too Many Requests

import requests
r = requests.get("https://example.com/path")
if r.status_code == 429:
    print("Too Many Requests")

const r = await fetch("https://example.com/path");
if (r.status === 429) {
  console.log("Too Many Requests");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 429);
// or:
http_response_code(429);

431 Request Header Fields Too Large #

El servidor rechaza la petición porque las cabeceras son demasiado grandes. RFC 6585.

Causa común

Cookie desmedida, Referer o Authorization muy largos.

Cuándo usarlo

Cuando las cookies de sesión crecen más allá del buffer del proxy inverso; recórtalas o mueve estado al cuerpo.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 431 Request Header Fields Too Large

import requests
r = requests.get("https://example.com/path")
if r.status_code == 431:
    print("Request Header Fields Too Large")

const r = await fetch("https://example.com/path");
if (r.status === 431) {
  console.log("Request Header Fields Too Large");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 431);
// or:
http_response_code(431);

451 Unavailable For Legal Reasons #

El recurso no está disponible por razones legales — orden de retirada, bloqueo geográfico o DMCA. RFC 7725.

Causa común

Orden judicial, retirada regulatoria, respuesta a derecho de borrado del RGPD.

Cuándo usarlo

Equipos de cumplimiento que necesitan ser transparentes con el motivo del bloqueo.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 451 Unavailable For Legal Reasons

import requests
r = requests.get("https://example.com/path")
if r.status_code == 451:
    print("Unavailable For Legal Reasons")

const r = await fetch("https://example.com/path");
if (r.status === 451) {
  console.log("Unavailable For Legal Reasons");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 451);
// or:
http_response_code(451);

500 Internal Server Error #

El servidor encontró una condición inesperada que le impidió completar la petición. RFC 9110 §15.6.1.

Causa común

Excepción no controlada, bug, dependencia rota, consulta desbocada.

Cuándo usarlo

Cajón de sastre. Registra siempre stack trace e ID de petición para que los usuarios lo citen.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 500 Internal Server Error

import requests
r = requests.get("https://example.com/path")
if r.status_code == 500:
    print("Internal Server Error")

const r = await fetch("https://example.com/path");
if (r.status === 500) {
  console.log("Internal Server Error");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 500);
// or:
http_response_code(500);

501 Not Implemented #

El servidor no admite la funcionalidad necesaria para atender la petición. RFC 9110 §15.6.2.

Causa común

Método desconocido, feature flag deshabilitada, ruta sin implementar.

Cuándo usarlo

Endpoints existentes pero aún no construidos. Prefiere 405 si otros métodos funcionan.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 501 Not Implemented

import requests
r = requests.get("https://example.com/path")
if r.status_code == 501:
    print("Not Implemented")

const r = await fetch("https://example.com/path");
if (r.status === 501) {
  console.log("Not Implemented");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 501);
// or:
http_response_code(501);

502 Bad Gateway #

El gateway o proxy recibió respuesta inválida del servidor upstream. RFC 9110 §15.6.3.

Causa común

El upstream devolvió HTTP malformado, la conexión cayó a mitad de respuesta o la aplicación reventó.

Cuándo usarlo

Proxies inversos (Nginx, Cloudflare, ALB) cuando la aplicación detrás falla.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 502 Bad Gateway

import requests
r = requests.get("https://example.com/path")
if r.status_code == 502:
    print("Bad Gateway")

const r = await fetch("https://example.com/path");
if (r.status === 502) {
  console.log("Bad Gateway");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 502);
// or:
http_response_code(502);

503 Service Unavailable #

El servidor no puede atender la petición ahora, normalmente por mantenimiento o sobrecarga. RFC 9110 §15.6.4.

Causa común

Ventana de mantenimiento, cola llena, autoscaler retrasado, brown-out deliberado.

Cuándo usarlo

Indisponibilidad planificada o protección frente a sobrecarga. Define siempre Retry-After para que el cliente reculée.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 503 Service Unavailable

import requests
r = requests.get("https://example.com/path")
if r.status_code == 503:
    print("Service Unavailable")

const r = await fetch("https://example.com/path");
if (r.status === 503) {
  console.log("Service Unavailable");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 503);
// or:
http_response_code(503);

504 Gateway Timeout #

El gateway o proxy no recibió respuesta a tiempo del servidor upstream. RFC 9110 §15.6.5.

Causa común

El upstream tardó más que el timeout configurado en el proxy.

Cuándo usarlo

Código lento, consultas atascadas, APIs externas colgadas.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 504 Gateway Timeout

import requests
r = requests.get("https://example.com/path")
if r.status_code == 504:
    print("Gateway Timeout")

const r = await fetch("https://example.com/path");
if (r.status === 504) {
  console.log("Gateway Timeout");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 504);
// or:
http_response_code(504);

505 HTTP Version Not Supported #

El servidor no admite la versión mayor de HTTP de la petición. RFC 9110 §15.6.6.

Causa común

Cliente que habla HTTP/2 a un servidor que solo maneja HTTP/1.0, o envía un token de versión desconocido.

Cuándo usarlo

Raro en la práctica. Bordes mal configurados o clientes muy antiguos.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 505 HTTP Version Not Supported

import requests
r = requests.get("https://example.com/path")
if r.status_code == 505:
    print("HTTP Version Not Supported")

const r = await fetch("https://example.com/path");
if (r.status === 505) {
  console.log("HTTP Version Not Supported");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 505);
// or:
http_response_code(505);

511 Network Authentication Required #

El cliente debe autenticarse para usar la red — típicamente un portal cautivo. RFC 6585.

Causa común

Wi-Fi de hotel o aeropuerto interceptando el tráfico hasta el login.

Cuándo usarlo

Portales cautivos en redes de paso. Los servidores normalmente no lo devuelven por sí mismos.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 511 Network Authentication Required

import requests
r = requests.get("https://example.com/path")
if r.status_code == 511:
    print("Network Authentication Required")

const r = await fetch("https://example.com/path");
if (r.status === 511) {
  console.log("Network Authentication Required");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 511);
// or:
http_response_code(511);

¿Qué son los códigos de estado HTTP?

Un código de estado HTTP es el número de tres dígitos que el servidor devuelve al inicio de cada respuesta. Se agrupan en cinco familias: 1xx informativo, 2xx éxito, 3xx redirección, 4xx error de cliente y 5xx error de servidor. Los códigos están definidos en la RFC 9110 (la especificación consolidada de 2022 que reemplaza la serie 7230–7235), con extensiones en la RFC 6585 (4xx/5xx adicionales), RFC 7725 (451), RFC 4918 (WebDAV) y RFC 8470 (425). Leer bien el estado es la diferencia entre corregir un bug en cinco minutos y perseguir un fantasma toda la tarde: un 404 del CDN indica que la ruta es errónea, un 502 del proxy indica que la aplicación cayó y un 401 sin WWW-Authenticate es un backend mal configurado. Esta página es una chuleta buscable — cada tarjeta incluye el nombre oficial, descripción basada en la RFC, causa típica y fragmentos listos para pegar en curl, Python, JavaScript o PHP.

Cómo usar la referencia

Escribe un código o parte de un nombre en la búsqueda, o filtra por familia con los chips. Cada tarjeta se abre y muestra la descripción técnica, causas comunes y un snippet por pestañas adaptable. Cada código tiene su propio ancla (p. ej. #404) para enlazar la documentación de tu equipo a un estado concreto.

Familias de estado de un vistazo

Rango	Familia	Significado
1xx	Informativo	Respuestas provisionales; rara vez se ven en la capa de aplicación.
2xx	Éxito	La petición se recibió, entendió y aceptó.
3xx	Redirección	Hace falta una acción adicional (URL distinta, validación de caché, etc.).
4xx	Error de cliente	La petición tuvo un problema (entrada incorrecta, sin auth, método equivocado).
5xx	Error de servidor	El servidor no pudo cumplir una petición aparentemente válida.

Preguntas frecuentes

¿De dónde salen estos códigos?

La RFC 9110 es la especificación canónica de 2022 que consolida la serie RFC 7231. Los códigos adicionales están en RFC 6585 (428, 429, 431, 511), RFC 7725 (451), RFC 4918 (WebDAV) y RFC 8470 (425).

¿Uso 401 o 403?

401 significa "no estás autenticado". 403 significa "estás autenticado pero no tienes permiso". El 401 debe incluir cabecera WWW-Authenticate con esquemas aceptados; el 403 no debería porque las credenciales no son el problema.

¿Diferencia entre 301 y 308?

Ambos indican redirección permanente. El 301 históricamente reescribe POST a GET en muchos clientes; el 308 conserva método y cuerpo. Usa 308 en APIs nuevas.

¿Cuándo devuelve mi CDN 502 frente a 504?

502 (Bad Gateway) significa que el upstream devolvió datos malformados o cerró la conexión. 504 (Gateway Timeout) significa que el upstream tardó demasiado. CloudFront, Cloudflare y Nginx los etiquetan distinto en los logs — ambos indican un problema en la aplicación.

¿404 o 410 para contenido borrado?

Usa 410 cuando el recurso se retiró a propósito y de forma permanente y quieres que los crawlers lo descarten rápido. 404 sirve para erratas o contenido que puede volver; también es una respuesta defendible cuando no quieres confirmar la existencia del recurso.

¿Es seguro copiar los fragmentos?

Son plantillas mínimas para leer y adaptar. Valida entradas, trata errores y respeta la semántica HTTP en tu código real — los ejemplos se la saltan por brevedad.