Códigos de error

HTTP

Code	Significado	Cuándo
400	Bad Request	Body mal formado, validación fallida.
401	Unauthorized	JWT inválido, expirado o ausente.
403	Forbidden	Permiso insuficiente.
404	Not Found	Recurso inexistente.
409	Conflict	Recurso en estado incompatible (ej. sesión ya conectada).
422	Unprocessable Entity	Validación de negocio fallida (ej. plantilla no aprobada).
429	Too Many Requests	Rate-limit excedido (especialmente en MCP).
500	Internal Server Error	Error inesperado del backend.
502	Bad Gateway	Error al comunicarse con Meta/Baileys/Messenger.
503	Service Unavailable	Mantenimiento o dependencia caída.
504	Gateway Timeout	Timeout al esperar respuesta upstream.

Formato

{
  "statusCode": 422,
  "error": "ValidationError",
  "message": "El campo 'template.name' es requerido",
  "details": { "field": "template.name" }
}

Troubleshooting común

• 401 con token válido → verificá que el token no esté en blacklist (logout reciente).
• 409 al iniciar sesión → la referencia ya tiene una sesión activa. Hacé logout primero.
• 422 con plantilla rechazada → la plantilla debe ser aprobada por Meta antes de enviar.
• 429 en MCP → esperá Retry-After header (en segundos).
• 502/504 recurrentes → revisá el estado de la dependencia upstream en el panel admin (sección "Salud").

Detalle: api-documentation/11-errores.mdx.