AllyOneMail / Errors and limits

Errors and limits

The shape of AllyOneMail API errors, the most common codes, when to retry and how the limits work.

Error format

Errors carry a stable machine code in error and human-readable text in message (in Portuguese). Branch on the HTTP status and on error, never on the text. Validation errors carry per-field details.

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

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

Codes

Status	`error`	When
`400`	`invalid_body` and others	Invalid body — see `details`.
`401`	`unauthenticated` · `invalid_api_key` · `expired_api_key`	No credential, unknown/revoked key or expired key.
`403`	`insufficient_scope`	The key lacks the operation's scope.
`404`	`not_found`	Nonexistent resource or one from another customer.
`409`	`IDEMPOTENCY_CONFLICT`	`idempotency_key` reused with different content.
`429`	`api_rate_limit_exceeded`	The key's per-minute limit.
`5xx`	—	Unexpected error or temporary unavailability.

When to retry

400, 401, 403, 404, 409: don't retry — fix the request or the credential.
429: wait for the minute to roll over.
5xx or timeout on send: retry with backoff using POST /api/v2/messages and the same idempotency_key — the retry never duplicates the email (see Sending emails).
202 processing is not an error: the first call with that key is still in progress.

Rate limit

Per key: per-minute limit configured on the key (default: 1,000) → 429 api_rate_limit_exceeded.
Per IP: 500,000 per hour, with X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset on every response.
Dashboard login: 5 attempts every 15 minutes per IP; after consecutive errors on the same email, the account responds 423 account_locked for a few minutes.