AllyOneMail / Errores y límites

Errores y límites

El formato de los errores de la API de AllyOneMail, los códigos más comunes, cuándo reintentar y cómo funcionan los límites.

Formato del error

Los errores traen un código estable para máquinas en error y un texto para humanos en message (en portugués). Decide por el estado HTTP y por error, nunca por el texto. Los errores de validación traen details por campo.

{ "error": "invalid_api_key", "message": "API key não encontrada ou inativa." }

{ "error": "invalid_body", "details": { "fieldErrors": { "email": ["Invalid email"] } } }

Códigos

Estado	`error`	Cuándo
`400`	`invalid_body` y otros	Cuerpo inválido — ver `details`.
`401`	`unauthenticated` · `invalid_api_key` · `expired_api_key`	Sin credencial, clave inexistente/revocada o expirada.
`403`	`insufficient_scope`	La clave no tiene el alcance de la operación.
`404`	`not_found`	Recurso inexistente o de otro cliente.
`409`	`IDEMPOTENCY_CONFLICT`	`idempotency_key` reutilizada con otro contenido.
`429`	`api_rate_limit_exceeded`	Límite por minuto de la clave.
`5xx`	—	Error inesperado o indisponibilidad temporal.

Cuándo reintentar

400, 401, 403, 404, 409: no reintentes — corrige la solicitud o la credencial.
429: espera a que cambie el minuto.
5xx o timeout en el envío: reintenta con backoff usando POST /api/v2/messages y la misma idempotency_key — el reintento nunca duplica el correo (ver Enviar correos).
202 processing no es un error: la primera llamada con esa clave aún está en curso.

Rate limit

Por clave: límite por minuto configurado en la clave (por defecto: 1.000) → 429 api_rate_limit_exceeded.
Por IP: 500.000 por hora, con X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset en toda respuesta.
Login en el panel: 5 intentos cada 15 minutos por IP; tras errores seguidos con el mismo e-mail, la cuenta responde 423 account_locked durante unos minutos.