AllyOneMail / Erros e limites

Erros e limites

Formato dos erros da API do AllyOneMail, códigos mais comuns, quando repetir e como funcionam os limites.

Formato do erro

Erros trazem um código estável para máquina em error e um texto para humanos em message (em português). Decida pelo status HTTP e por error, nunca pelo texto. Erros de validação trazem 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

Status	`error`	Quando
`400`	`invalid_body` e outros	Corpo inválido — veja `details`.
`401`	`unauthenticated` · `invalid_api_key` · `expired_api_key`	Sem credencial, chave inexistente/revogada ou expirada.
`403`	`insufficient_scope`	A chave não tem o escopo da operação.
`404`	`not_found`	Recurso inexistente ou de outro cliente.
`409`	`IDEMPOTENCY_CONFLICT`	`idempotency_key` reutilizada com outro conteúdo.
`429`	`api_rate_limit_exceeded`	Limite por minuto da chave.
`5xx`	—	Erro inesperado ou indisponibilidade temporária.

Quando repetir

400, 401, 403, 404, 409: não repita — corrija o pedido ou a credencial.
429: espere o minuto virar.
5xx ou timeout no envio: repita com backoff usando POST /api/v2/messages e a mesma idempotency_key — a repetição nunca duplica o e-mail (veja Enviar e-mails).
202 processing não é erro: a primeira chamada com aquela chave ainda está em andamento.

Rate limit

Por chave: limite por minuto configurado na chave (padrão: 1.000) → 429 api_rate_limit_exceeded.
Por IP: 500.000 por hora, com X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset em toda resposta.
Login no painel: 5 tentativas a cada 15 minutos por IP; depois de erros seguidos no mesmo e-mail, a conta responde 423 account_locked por alguns minutos.