Errors & rate limits

Error shape

Aigeon returns non-200 HTTP status codes for authentication failures (401, 403), request validation failures (400) and internal server errors (5xx). Business-level failures return 200 with a non-zero code in the JSON envelope, so a 200 alone does not mean the operation succeeded:

{
  "code": -1,
  "status": "failed",
  "message": "send_group_id is required",
  "data": null
}

Clients should treat code != 0 as a failure and surface message to logs/callers.

The reverse also needs saying: code: 0 means the request was accepted, not that the work it started has finished. For sends in particular, see a 200 is not a delivery receipt.

Common error codes

HTTP	`code`	Meaning
400	102	Missing required parameter. Check `message` for the field name.
400	101	Parameter present but invalid (bad email, malformed HTML, `send_time` in the past).
401	-1	Missing or invalid `X-Api-Token`.
403	-1	The key doesn't include the required permission scope.
404	—	Endpoint or resource not found.
429	—	Rate limit exceeded. Back off.
200	4003	Campaign created but scheduling failed; it's saved as a draft.
500	-1	Internal server error. Safe to retry with backoff.
502-504	—	Transient gateway/timeout. Retry with backoff.

Rate limits

Default quotas per API key:

Writes (POST/PATCH/DELETE): 600 requests per minute, 20 requests per second burst.
Reads (GET): 1,200 requests per minute, 50 requests per second burst.
Sending endpoints (flow/send-email-through-flow etc.): 300 requests per minute per org.

Rate-limit responses include Retry-After (seconds) — respect it and back off. Bulk operations that naturally exceed these (imports, analytics backfills) should use the dedicated async endpoints that queue work server-side.

Retry policy

Safe to retry on 5xx, 429, and network errors. Not safe to retry on 4xx — the request is malformed, retrying won't help.

Recommended backoff: 500ms, 1s, 2s, 4s, give up. Always jitter (base * (1 + random(0, 0.3))) to avoid thundering-herd retries against a struggling endpoint.

Idempotency

Several write endpoints accept an Idempotency-Key header. When present, Aigeon stores the first successful response for that key for 24 hours and returns the same response on any retry, so you can safely retry on network failures without double-creating resources. Use a v4 UUID per logical operation.