Códigos de Error

Cada respuesta de error de la API de MailLand incluye un campo code con un código de error legible por máquina y un campo message con una descripción legible por humanos.

Formato de Respuesta de ErrorCopiar enlace de la sección

{
  "code": "DOMAIN_NOT_VERIFIED",
  "message": "Domain is not verified",
  "timestamp": "2026-02-18T12:35:00Z",
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}

Algunos errores incluyen details adicionales:

{
  "code": "IP_RATE_LIMIT_EXCEEDED",
  "message": "Too many requests from this IP. Retry after 45 seconds.",
  "details": {
    "limit": 300,
    "current": 301,
    "retryAfter": 45,
    "resetAt": "2026-02-18T12:35:00Z"
  }
}

Validación de Solicitud (400)Copiar enlace de la sección

Se devuelve cuando el cuerpo de la solicitud, los parámetros de consulta o los encabezados están malformados o faltan campos obligatorios.

Autenticación (401)Copiar enlace de la sección

Se devuelve cuando la solicitud no tiene credenciales o las credenciales son inválidas.

Autenticación de Dos FactoresCopiar enlace de la sección

Los fallos de 2FA devuelven 400 INVALID_REQUEST con un message descriptivo (por ejemplo, "Invalid code", "2FA is already enabled"). No existen códigos de error 2FA dedicados, lea el campo message.

Autorización (403)Copiar enlace de la sección

Se devuelve cuando el usuario autenticado no tiene permiso para realizar la acción solicitada.

No Encontrado (404)Copiar enlace de la sección

Se devuelve cuando el recurso solicitado no existe o pertenece a un espacio de trabajo diferente.

Conflicto (409)Copiar enlace de la sección

Se devuelve cuando la operación entra en conflicto con el estado actual del recurso.

Dominio y Envío (422)Copiar enlace de la sección

Se devuelve cuando la solicitud está bien formada pero no puede procesarse debido a restricciones de lógica de negocio.

Pago Requerido (402)Copiar enlace de la sección

Se devuelve cuando el saldo de crédito del espacio de trabajo no puede cubrir la operación solicitada.

Limitación de Velocidad (429)Copiar enlace de la sección

Se devuelve cuando la solicitud excede los límites de velocidad. Normalmente incluye el encabezado Retry-After; si falta, use retroceso exponencial en lugar de asumir que no hay espera.

Límites de Velocidad de la APICopiar enlace de la sección

Límites de Velocidad de Envío de Correo ElectrónicoCopiar enlace de la sección

Capacidad de la plataforma (429)Copiar enlace de la sección

Estos rechazos significan que en este momento es la plataforma, y no la cuota de su cuenta, la que limita los envíos nuevos. Cada uno es un 429 con cabecera Retry-After, no se puso nada en cola y es seguro reintentar la misma solicitud. Por SMTP son un 421 Try again later: <message> transitorio. El message es el texto en inglés que devuelve la API.

Los correos ya aceptados nunca se ven afectados. Trátelos como cualquier otro 429: espere, respete Retry-After y reintente. No hay nada que configurar ni ampliar.

Límites de StreamCopiar enlace de la sección

transactional_recipient_limit_exceeded y marketing_recipient_limit_exceeded son 400, no 429: vea la sección Validación de Solicitud arriba. BATCH_NOT_ALLOWED_FOR_TRANSACTIONAL también es 400: un envío por lotes no está permitido en una credencial transaccional independientemente de los límites de velocidad.

Cuota y FacturaciónCopiar enlace de la sección

Motor de PolíticasCopiar enlace de la sección

Errores del Servidor (5xx)Copiar enlace de la sección

Manejo de ErroresCopiar enlace de la sección

Estrategia de ReintentosCopiar enlace de la sección

Lectura de Encabezados de Límite de VelocidadCopiar enlace de la sección

La mayoría de las respuestas incluyen X-RateLimit-Limit y X-RateLimit-Remaining:

Un 429 basado en IP añade además:

Próximos PasosCopiar enlace de la sección

• Límites de Velocidad: niveles detallados de límites de velocidad y mejores prácticas
• Autenticación: administración de tokens y API keys
• Registro de Cambios: rastree cambios en la API