Códigos de error

Formato de error

En caso de error, la respuesta suele tener esta estructura:

{
  "success": false,
  "error": "Descripción del error"
}

Errores por código HTTP

400 Bad Request

Cuándo ocurre: Campos requeridos faltantes, formato inválido o dominio del remitente no coincide.

Ejemplos de mensajes:

• "Missing required field: from"
• "Missing required field: to"
• "Missing required field: subject"
• "At least one of 'text' or 'html' is required"
• "Invalid sender domain"

Cómo solucionarlo:

• Verifica que envíes from, to, subject y al menos uno de text o html
• Asegúrate de que el dominio en from coincida con el dominio en la URL (:domain)
• Revisa que las direcciones de correo tengan formato válido

401 Unauthorized

Cuándo ocurre: Falta la API key o es inválida.

Ejemplos de mensajes:

• "Missing API key"
• "Invalid API key"

Cómo solucionarlo:

• Incluye el header Authorization: Bearer yk-tu-api-key (o Basic Auth)
• Verifica que la API key tenga el formato correcto (yk- + 64 caracteres hex)
• Comprueba que la clave no haya sido revocada
• Si la perdiste, crea una nueva desde el Dashboard

403 Forbidden

Cuándo ocurre: La API key no está autorizada para el dominio usado en la URL.

Ejemplos de mensajes:

• "API key not authorized for this domain"

Cómo solucionarlo:

• Asegúrate de que el dominio en la URL (/api/mail/v1/:domain/messages) sea el mismo al que está asociada tu API key
• Cada API key solo funciona con un dominio; si tienes varios, usa la clave correcta

429 Too Many Requests

Cuándo ocurre: Se superó el límite de 100 peticiones por minuto.

Ejemplo de mensaje:

• "Rate limit exceeded. Max 100 requests per minute."

Cómo solucionarlo:

• Reduce la frecuencia de envío
• Implementa colas y envíos por lotes
• Usa backoff exponencial al recibir 429 antes de reintentar

500 Internal Server Error

Cuándo ocurre: Error interno del servidor.

Cómo solucionarlo:

• Reintenta la petición después de unos segundos
• Si el problema persiste, contacta al equipo de soporte de Yolani

Resumen rápido