Errores

La API de Emailit usa códigos de estado HTTP para indicarte si una petición ha funcionado. Los códigos del rango 2xx indican éxito, los códigos 4xx indican que hay que cambiar algo en la petición y los códigos 5xx indican que algo ha fallado por nuestra parte. Esta página describe los cuerpos de error, todos los códigos de estado que devuelve la API y cómo solucionar los errores más habituales.

Formatos de las respuestas de error

Todo cuerpo de error es un objeto JSON con un campo error. Su forma exacta depende de dónde falló la petición. Escribe la gestión de errores para que lea error, después message si está presente y, por último, cualquier campo adicional que documente el endpoint.

Errores de la petición

Los fallos de autenticación, los errores de permisos, el JSON mal formado y otros errores que se producen antes de que se ejecute un endpoint usan el formato de error HTTP estándar:

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "API key required"
}

Errores de validación

Cuando un parámetro de consulta o un campo del cuerpo tiene un tipo incorrecto, falta o está fuera de rango, la API rechaza la petición con 400 antes de ejecutarla y enumera cada problema en details:

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Validation error",
  "details": [
    {
      "instancePath": "/limit",
      "schemaPath": "#/properties/limit/maximum",
      "keyword": "maximum",
      "params": { "comparison": "<=", "limit": 100 },
      "message": "must be <= 100"
    }
  ]
}

instancePath señala el campo (/limit, /to, /attachments/0/filename) y message describe la regla que incumple. En algunos endpoints, como Enviar un email, estos errores solo devuelven {"error": "Bad Request"}.

Errores de recursos

Los errores que genera un endpoint, como un objeto que no existe o un nombre duplicado, devuelven error y a menudo message:

{
  "error": "Email not found",
  "message": "Email with ID 'em_4KYof1ZzXndZE2VPi0DgULiekG8' not found in your workspace"
}

Algunos errores añaden campos que te ayudan a resolver el problema:

Errores de validación del envío

Enviar un email y Reenviar un email comprueban todo el mensaje de una vez y devuelven todos los problemas en validation_errors:

{
  "error": "Validation failed",
  "validation_errors": [
    "Missing required field: subject",
    "Invalid to email address at index 1: ada@example"
  ]
}

Errores por campo

Las plantillas, las campañas y las automatizaciones devuelven los problemas de validación agrupados por campo:

{
  "message": "Validation failed",
  "errors": {
    "alias": ["Alias must contain only lowercase letters (a-z), numbers (0-9), underscores (_), and hyphens (-)"]
  }
}

Errores de límite de velocidad

Las respuestas 429 de los endpoints de envío incluyen el límite que has alcanzado y cuánto tiempo debes esperar. Consulta Límites de velocidad.

{
  "error": "Rate limit exceeded",
  "message": "Too many requests. Maximum 2 messages per second allowed.",
  "limit": 2,
  "current": 2,
  "retry_after": 1
}

Códigos de estado HTTP

Errores habituales y cómo solucionarlos

Reintentar de forma segura

• Reintenta las respuestas 429, 500 y 503 tras una espera. Usa la cabecera retry-after cuando esté presente y, si no, una espera exponencial. Límites de velocidad incluye código de ejemplo.
• No reintentes otros errores 4xx sin cambios. Seguirán fallando igual hasta que corrijas la petición.
• Cuando reintentes un envío tras un tiempo de espera agotado o un error 5xx, reutiliza la misma Idempotency-Key para que el email no se envíe dos veces.

Ver también