Errores

Todas las respuestas de error de la API de MailerDash siguen un formato unificado inspirado en Stripe. Esto facilita el manejo programático: puedes distinguir qué tipo de error ocurrió (y cómo reaccionar) sin parsear el mensaje de texto.

---

Estructura de una respuesta de error

{
  "error": {
    "type": "validation_error",
    "code": "domain_unauthorized",
    "message": "The from domain is not authorized for this key.",
    "param": "from.email"
  }
}

Campo	Tipo	Descripción
type	string	Categoría del error (ver tabla abajo). Determina la estrategia de retry.
code	string	Código machine-readable específico.
message	string	Descripción human-readable en inglés.
param	string (opcional)	Campo o parámetro que causó el error, cuando aplica.
details	array (opcional)	Lista de sub-errores para casos de validación múltiple.

---

Tipos de error (type)

El campo type es categórico y te permite decidir la estrategia sin leer code ni message:

type	HTTP	Cuándo usarlo
validation_error	400 / 422	El request tiene campos inválidos o faltantes. No reintentar sin corrección.
authentication_error	401	Token ausente, malformado o inválido. Revisar la API key.
authorization_error	403	Autenticado pero sin permisos. La key no tiene el scope necesario.
not_found_error	404	El recurso solicitado no existe.
rate_limit_error	429	Se excedió el límite de tasa o la cuota mensual. Reintentar con backoff.
conflict_error	409	Conflicto con el estado actual (p.ej. recurso ya existe).
payload_too_large_error	413	El body excede el tamaño permitido (p.ej. attachments demasiado grandes).
idempotency_error	409	La idempotency key ya se usó con un payload diferente.
smtp_error	5xx	Error al entregar el correo via SMTP.
api_error	5xx	Error interno del servidor. Reintentar con backoff exponencial.

---

Códigos específicos (code)

Consejo

Programa tu manejo de errores contra type (estable) y code (específico). El campo message es solo para humanos y puede cambiar sin aviso.

Errores de envío transaccional

code	type	Descripción
domain_unauthorized	authorization_error	El dominio del campo from no está autorizado para esta API key.
email_not_verified	authorization_error	La cuenta no ha verificado su email; los envíos están bloqueados hasta hacerlo.
free_requires_verified_domain	authorization_error	El plan gratuito requiere un dominio verificado para enviar.
monthly_quota_exceeded	rate_limit_error	Se alcanzó la cuota mensual de envíos del plan.
rate_limit_exceeded	rate_limit_error	Se superó el límite de requests por minuto (rate_per_min).

Errores de dominios

code	type	Descripción
max_domains_exceeded	validation_error	Alcanzaste el límite de dominios permitidos por tu plan.
domain_taken	conflict_error	El dominio ya está registrado en otra cuenta de la plataforma.
reserved_domain	validation_error	El dominio está reservado y no puede ser registrado por clientes.
cname_delegation_disabled	validation_error	La delegación CNAME no está habilitada para esta cuenta.

Errores de API keys

code	type	Descripción
max_api_keys_exceeded	validation_error	Alcanzaste el límite de API keys de tu plan.
key_not_linked	authorization_error	El JWT del usuario no tiene ninguna API key vinculada para el recurso solicitado.
already_revoked	conflict_error	La API key ya fue revocada.
wrong_password	authentication_error	La contraseña proporcionada es incorrecta (operaciones que requieren confirmación).

Errores de billing y planes

code	type	Descripción
billing_unavailable	api_error	El sistema de billing no está disponible en este momento.
no_billing_account	validation_error	La cuenta no tiene una suscripción Stripe activa.
no_active_subscription	validation_error	No hay suscripción activa para esta operación.
overage_not_offered	validation_error	El plan actual no ofrece envíos de overage.
package_not_selectable	validation_error	El plan solicitado no está disponible para selección.
already_subscribed	conflict_error	Ya tienes este plan activo.

Errores generales

code	type	Descripción
not_found	not_found_error	El recurso no existe.
unauthorized	authentication_error	Token ausente o inválido.
forbidden	authorization_error	Sin permisos para esta operación.
payload_too_large	payload_too_large_error	Body o attachments demasiado grandes.
internal_error	api_error	Error interno del servidor.
bad_request	validation_error	Request malformado.

---

Errores de validación múltiple

Cuando un solo request tiene varios campos inválidos, la respuesta incluye el array details:

{
  "error": {
    "type": "validation_error",
    "code": "invalid",
    "message": "Request validation failed",
    "details": [
      { "code": "required", "message": "'subject' is required", "param": "subject" },
      { "code": "invalid_format", "message": "'from.email' must be a valid email", "param": "from.email" }
    ]
  }
}

---

Ejemplo de manejo en Node.js

const res = await fetch('https://api.mailerdash.com/v1/mail/send', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MAILERDASH_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ from: { email: 'noreply@mi-app.com' }, to: [...], subject: '...', text: '...' }),
});

if (!res.ok) {
  const { error } = await res.json();

  if (error.type === 'rate_limit_error') {
    // Reintentar después de un backoff — el header Retry-After puede indicar cuándo
    console.warn('Rate limit alcanzado, reintentando en 60s...', error.code);
  } else if (error.type === 'validation_error') {
    // No reintentar — corregir el request
    console.error('Error de validación:', error.code, error.param);
  } else if (error.type === 'authentication_error') {
    // Revisar la API key
    console.error('API key inválida o sin permisos');
  } else {
    console.error('Error inesperado:', error);
  }
}

Ver la referencia completa de endpoints en /reference/transactional/ y /reference/bulk/.