Codigos de error

Formato de errores HTTP y causas habituales.

Las respuestas de error siguen un JSON uniforme:

{
  "statusCode": 403,
  "message": "Missing required API key scope: email:send",
  "path": "/emails/send",
  "timestamp": "2026-06-30T12:00:00.000Z"
}

Codigos HTTP

Codigo	Significado
400	Validacion fallida (campo requerido, email invalido)
401	JWT o API key invalida / expirada
403	Scope insuficiente, rol o tenant no autorizado
404	Recurso no encontrado
409	Conflicto (duplicado, estado invalido)
422	Regla de negocio (ej. destinatario suprimido)
429	Rate limit global o cuota mensual superada

Cuota excedida (429)

Cuando superas el 110 % del limite mensual:

{
  "statusCode": 429,
  "message": "Monthly email quota exceeded (115%). Upgrade your plan to continue sending.",
  "quota": {
    "limit": 100,
    "used": 115,
    "percentage": 115
  }
}

Rate limit

En produccion: ~300 peticiones/minuto por IP o usuario JWT (configurable). Headers:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1719763200

Rutas de auth publico (/auth/login, /auth/register) tienen limite mas estricto: 15 peticiones / 15 minutos.

SDK

El paquete mailingcore-js lanza MailingCoreError con .status y .detail para manejo en cliente.