Referencia

Referencia de códigos de estado HTTP para desarrolladores de bots

La pregunta más útil sobre un código no es qué significa sino qué debe hacer tu bot a continuación. Escribe un código o una palabra para filtrar.

100

Continue

El servidor recibió las cabeceras; el cliente puede enviar el cuerpo.

Qué debe hacer un bot: Lo gestiona tu librería HTTP; casi nunca aparece en el código del bot.

101

Switching Protocols

El servidor acepta cambiar de protocolo, normalmente a WebSocket.

Qué debe hacer un bot: Esperado cuando una conexión gateway (Discord, Slack Socket Mode) pasa a WebSocket.

200

OK

La petición se completó correctamente.

Qué debe hacer un bot: Éxito. En webhooks, responde 200 rápido para que la plataforma no reintente.

201

Created

Se creó un recurso nuevo.

Qué debe hacer un bot: Éxito; lee la cabecera Location o el cuerpo para obtener el id del recurso.

202

Accepted

Aceptada para procesar, pero aún no terminada.

Qué debe hacer un bot: Respuesta ideal de un webhook cuando encolas trabajo. Consulta o espera un callback para el resultado.

204

No Content

Éxito sin cuerpo de respuesta.

Qué debe hacer un bot: Éxito. No intentes parsear JSON de un cuerpo vacío. Discord lo devuelve en muchas acciones.

206

Partial Content

Solo se devuelve parte del recurso, según la cabecera Range.

Qué debe hacer un bot: Se usa al reanudar descargas grandes.

301

Moved Permanently

El recurso tiene una nueva URL permanente.

Qué debe hacer un bot: Actualiza la URL en tu configuración. Los emisores de webhooks no suelen seguir redirecciones; registra la URL final.

302

Found

Redirección temporal a otra URL.

Qué debe hacer un bot: Síguela en peticiones GET si tu cliente lo permite; no la uses en endpoints de webhooks.

304

Not Modified

La copia en caché sigue siendo válida (petición condicional).

Qué debe hacer un bot: Buena noticia para scrapers y lectores de feeds: reutiliza la caché y ahorra ancho de banda.

307

Temporary Redirect

Redirección temporal que mantiene el método y el cuerpo.

Qué debe hacer un bot: Es seguro repetir el mismo POST en la nueva URL.

308

Permanent Redirect

Redirección permanente que mantiene el método y el cuerpo.

Qué debe hacer un bot: Actualiza las URLs guardadas; repite la petición en la nueva ubicación.

400

Bad Request

La petición está mal formada o tiene parámetros no válidos.

Qué debe hacer un bot: No reintentes sin cambios. Registra la descripción del error: Telegram y Discord indican qué campo falla.

401

Unauthorized

Autenticación ausente o no válida.

Qué debe hacer un bot: Revisa el token y el formato de la cabecera (Bot, Bearer). Detente y avisa: reintentar no sirve y puede marcar el token.

403

Forbidden

Autenticado, pero sin permiso para esto.

Qué debe hacer un bot: Faltan permisos o scopes, o el usuario bloqueó al bot. No reintentes; marca el chat como inactivo si hay bloqueo.

404

Not Found

El recurso o endpoint no existe.

Qué debe hacer un bot: Revisa la ruta, la versión de la API y los ids. Si se borró el mensaje o canal, descarta el trabajo.

405

Method Not Allowed

El endpoint no acepta este método HTTP.

Qué debe hacer un bot: Usa el método documentado (a menudo POST). Tu webhook debería devolver 405 a GET si solo acepta POST.

406

Not Acceptable

El servidor no puede producir el formato pedido en Accept.

Qué debe hacer un bot: Envía Accept: application/json o elimina la cabecera.

408

Request Timeout

El servidor dejó de esperar la petición.

Qué debe hacer un bot: Reintenta con backoff; revisa subidas lentas.

409

Conflict

La petición entra en conflicto con el estado actual.

Qué debe hacer un bot: Telegram devuelve 409 si getUpdates se ejecuta con un webhook activo o hay dos pollers a la vez. Corrige la configuración, no reintentes.

410

Gone

El recurso se eliminó de forma permanente.

Qué debe hacer un bot: Elimínalo de tu base de datos y deja de pedirlo.

411

Length Required

Se requiere la cabecera Content-Length.

Qué debe hacer un bot: Envía el cuerpo como buffer o cadena para que el cliente fije Content-Length.

412

Precondition Failed

Una cabecera condicional (If-Match) no coincidió.

Qué debe hacer un bot: Alguien cambió el recurso; vuelve a leerlo y reaplica.

413

Content Too Large

El cuerpo de la petición es demasiado grande.

Qué debe hacer un bot: Comprime o divide el fichero, o usa el endpoint de subida y los límites de la plataforma.

414

URI Too Long

La URL es demasiado larga.

Qué debe hacer un bot: Mueve los parámetros de la query string a un cuerpo POST.

415

Unsupported Media Type

El formato del cuerpo no está soportado.

Qué debe hacer un bot: Indica el Content-Type correcto (application/json, multipart/form-data).

418

I'm a teapot

Código de broma de RFC 2324, a veces usado para rechazar bots.

Qué debe hacer un bot: Trátalo como 403: el sitio no quiere tráfico automatizado.

422

Unprocessable Content

Petición bien formada con errores semánticos (falló la validación).

Qué debe hacer un bot: Corrige el payload con los detalles de validación; no reintentes sin cambios.

425

Too Early

El servidor no procesará una petición que podría repetirse.

Qué debe hacer un bot: Reintenta tras completar el handshake TLS (evita 0-RTT en llamadas no idempotentes).

426

Upgrade Required

El cliente debe cambiar a otro protocolo.

Qué debe hacer un bot: Actualiza la versión de TLS o HTTP según la cabecera Upgrade.

428

Precondition Required

El servidor requiere una petición condicional.

Qué debe hacer un bot: Envía If-Match con el ETag actual.

429

Too Many Requests

Se superó el límite de peticiones.

Qué debe hacer un bot: Espera Retry-After (Telegram: parameters.retry_after, Discord: retry_after en segundos) y reintenta con backoff con jitter. Encola los envíos por chat.

431

Request Header Fields Too Large

Las cabeceras son demasiado grandes.

Qué debe hacer un bot: Recorta cookies o cabeceras personalizadas demasiado grandes.

451

Unavailable For Legal Reasons

Bloqueado por motivos legales en esta región.

Qué debe hacer un bot: No intentes saltártelo; registra y omite.

500

Internal Server Error

El servidor falló de forma inesperada.

Qué debe hacer un bot: Reintenta con backoff exponencial y jitter, pocas veces. Si tu webhook devuelve 500, la plataforma reintentará la entrega.

501

Not Implemented

El servidor no admite esta funcionalidad.

Qué debe hacer un bot: No reintentes; usa otro método o endpoint.

502

Bad Gateway

Un proxy o gateway recibió una respuesta no válida.

Qué debe hacer un bot: Transitorio: reintenta con backoff. Telegram y Discord lo devuelven a veces durante incidencias.

503

Service Unavailable

Sobrecargado o en mantenimiento.

Qué debe hacer un bot: Reintenta más tarde respetando Retry-After si existe. Usa un circuit breaker para no acumular peticiones.

504

Gateway Timeout

Un servidor anterior no respondió a tiempo.

Qué debe hacer un bot: Reintenta peticiones idempotentes. En las demás, comprueba primero si la acción se realizó.

507

Insufficient Storage

El servidor no puede almacenar lo necesario.

Qué debe hacer un bot: Reintenta mucho más tarde o contacta al proveedor.

520

Web Server Returned an Unknown Error

Específico de Cloudflare: el origen devolvió una respuesta vacía o inesperada.

Qué debe hacer un bot: Si es tu origen, revisa sus registros. Si es una API, reintenta con backoff.

521

Web Server Is Down

Específico de Cloudflare: el origen rechazó la conexión.

Qué debe hacer un bot: Tu servidor o túnel está caído; reinícialo.

522

Connection Timed Out

Específico de Cloudflare: la conexión TCP con el origen expiró.

Qué debe hacer un bot: Revisa el firewall y que el origen sea accesible.

524

A Timeout Occurred

Específico de Cloudflare: el origen tardó más de 100 segundos.

Qué debe hacer un bot: Pasa el trabajo largo a una tarea en segundo plano y devuelve 202 rápido.

Reintentar o no: la versión corta

  • Reintentar con backoff y jitter: 408, 429 (tras Retry-After), 500, 502, 503, 504.
  • Corregir antes la petición: 400, 405, 413, 415, 422.
  • Parar y avisar o limpiar: 401, 403, 404, 410.

Relacionado: calculadora de backoff, guía de fiabilidad y límites.