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)
413	Mensaje demasiado grande (MIME > 10 MB)
422	Regla de negocio (ej. destinatario suprimido)
429	Rate limit global o cuota mensual superada

Codigos de error de aplicacion

Cada respuesta de error incluye tambien un code legible por maquina junto al estado HTTP. Codigos habituales:

Codigo	Significado
`VALIDATION_ERROR`	Un campo fallo la validacion (400)
`HTML_BODY_REQUIRED`	Sin `html`/`htmlBody` y sin plantilla (400)
`BATCH_LIMIT_EXCEEDED`	Mas de 100 destinatarios en una llamada (400)
`HAS_EMAIL_HISTORY`	No se puede borrar una version de plantilla o proyecto con historial de envios — los logs son append-only (400)
`TEMPLATE_NOT_FOUND`	Slug o id de plantilla desconocido (404)
`TEMPLATE_NOT_PUBLISHED`	La plantilla no tiene version publicada para enviar
`EMAIL_TOO_LARGE`	El mensaje construido supera el limite de 10 MB (413)
`QUOTA_EXCEEDED`	Cuota mensual de emails superada (429)

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.