Pagination, idempotency and rate limits
How the IotaBot API pages through lists, makes retries safe with Idempotency-Key, and limits requests and monthly messages.
Pagination
Lists return items, has_more and next_cursor. Pass next_cursor as starting_after to get the next page; limit is 1–100 (25 by default).
GET /v1/conversations?limit=50&starting_after=6a4b9e21c3f1a2b3c4d5e6f7Idempotency
Send an Idempotency-Key header on POST requests. A retry with the same key and the same body returns the first result — with Idempotent-Replayed: true — instead of sending a second message. Keys are remembered for 24 hours, per API key. Reusing one with a different body is refused with 422 idempotency_key_reused.
Rate limits
On paid plans each key may make 20 requests a second and 300 a minute (Enterprise plans can be raised). Every response says how much is left in X-RateLimit-Limit and X-RateLimit-Remaining; over the limit you get 429 rate_limited with Retry-After in seconds.
Monthly API messages
Messages sent through the API count against a monthly allowance set by your plan (see GET /v1/usage). Only messages the channel accepts count — a refused send gives its message back, a retry with the same Idempotency-Key counts once, and webhooks never count. At the limit, sends return 429 api_quota_exceeded until the 1st.
Channel rules
The API refuses what the channel itself would refuse, before sending: WhatsApp and Instagram allow free text only within 24 hours of the customer's last message (window_closed) — on WhatsApp an approved template works at any time; email goes only from a verified domain; website chats accept messages only while open.