Rate limits, retries, and idempotency

Make AstroM8 integrations reliable under retries, throttling, and asynchronous work.

Rate limits

Limits protect account capacity and report infrastructure. When an endpoint returns 429, back off and retry only after the response’s retry guidance. Do not fan out retries from several workers at once.

For bursty workloads, queue requests per API key and use bounded concurrency. Batch endpoints are preferable to an unbounded client-side loop when the reference offers one.

Idempotency

For endpoints that create paid work, send an Idempotency-Key generated by your system.

Idempotency-Key: order-123-report-natal-v1

Use the same key only with the same payload. Reusing it with a different payload returns a conflict rather than creating a second charge. Store the accepted response and reconcile with the job endpoint before submitting a new request.

Retry policy

• Retry network failures only when an idempotency key is present for a billable operation.
• Retry 429 and transient 5xx responses with exponential backoff and jitter.
• Do not retry 400, 401, 402, or 403 until the underlying input, key, credits, or tier has changed.
• Poll asynchronous jobs at a measured interval and stop at a terminal succeeded or failed state.

Errors

Error bodies contain safe client-facing details. Capture request identifiers and stable error codes in your own observability system; do not expose raw upstream provider errors to end users.