Errors & rate limits

Error shape

Aigeon returns non-200 HTTP status codes only for authentication failures (401, 403) and internal server errors (5xx). All other errors return 200 with a non-zero code in the JSON envelope:

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

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

Common error codes

| HTTP | code | Meaning | | --- | --- | --- | | 400 | 400100 | Missing or malformed parameter. Check message for the field name. | | 401 | — | Missing or invalid X-Api-Token. | | 403 | — | The key doesn't include the required permission scope. | | 404 | — | Endpoint or resource not found. | | 429 | 429001 | Rate limit exceeded. Back off. | | 500 | 500001 | 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.