> ## Documentation Index
> Fetch the complete documentation index at: https://docs.astrom8.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```http theme={null}
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.