Rate Limits and Idempotency - Simply Tokenized API

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

Selected write operations require an idempotency key to safely retry requests without creating duplicate side effects.

Idempotency header

Send a unique key with each write request that supports idempotency:

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

Endpoints that require the header

Endpoint	Method
`/api/offerings/{offeringId}/orders`	`POST`
`/api/accounts`	`POST`
`/api/accounts/{accountId}`	`PATCH`
`/api/accounts/{accountId}/benefiting-persons`	`POST`

Requests to these endpoints without X-Idempotency-Key return 400 with code validation_failed. PATCH /api/offerings/{offeringId}/orders/{orderId}/cancel does not use idempotency. POST /api/auth and all GET endpoints do not require a key.

Behavior

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

Example

curl -X POST "https://dev.api.floris3.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.

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.

​Rate limits

​API requests

​Authentication failures

​Idempotency

​Idempotency header

​Endpoints that require the header

​Behavior

​Example

​When to use idempotency keys