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

# Rate Limits and Idempotency

> API rate limits and idempotent write operations.

## Rate limits

### API requests

All endpoints are rate-limited to **30 requests per minute** per API credential.

When exceeded, the API returns:

* HTTP status: **429 Too Many Requests**
* Error code: `rate_limited`

### Authentication failures

Failed authentication attempts are tracked per API credential. After **3 consecutive failures**, an email is sent to the tenant administrators.

## Idempotency

Write operations (`POST`, `PUT`, `PATCH`, `DELETE`) support idempotency to safely retry requests without creating duplicate side effects.

### Idempotency header

Send a unique key with each write request:

```
X-Idempotency-Key: your-unique-key-here
```

| Property            | Value                                      |
| ------------------- | ------------------------------------------ |
| Header names        | `X-Idempotency-Key` or `x-idempotency-key` |
| Max key length      | 128 characters                             |
| Cached response TTL | 24 hours                                   |
| In-progress lock    | 60 seconds                                 |

### Behavior

1. First request with a given key executes normally
2. If the same key is sent again while processing, the API returns **409** with code `idempotency_in_progress`
3. After a successful response (2xx), subsequent requests with the same key return the cached response

### Example

```bash theme={null}
curl -X POST "https://dev.go.simplytokenized.com/_api/offerings/{offeringId}/orders" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: order-create-abc123" \
  -d '{ "account_id": "...", "units": "10000000000" }'
```

`units` is the token amount in the **smallest unit**. For an offering with `decimals: 8`, ordering **10 tokens** means `"units": "10000000000"` (10 followed by eight zeros). See [Units and decimals](/guides/units-and-decimals).

### When to use idempotency keys

* Network retries after timeouts
* Queue workers that may deliver the same job twice
* Any create or update operation where duplicates would cause problems

GET requests are naturally idempotent and do not require an idempotency key.