Errors, rate limits & pagination

Errors

Errors are returned with a standard HTTP status and a JSON body with a detail field carrying a machine-readable code:

{ "detail": "conversation_not_found" }

Common codes

• 401 — missing, malformed, or revoked API key.
• 403 developer_api_not_available — the project’s plan doesn’t include the API.
• 404 conversation_not_found / contact_not_found.
• 400 conversation_closed, content_required, group_conversations_not_supported, invalid_priority, use_assignment_to_reach_processing, escalation_reason_required, invalid_cursor, invalid_updated_since.
• 429 rate_limited — slow down (see below).

Rate limits

Limits are per API key. Exceeding one returns 429 with rate_limited.

• Reads (list/get) — 120 requests/minute.
• Send a message — 60 requests/minute.
• Update a conversation — 60 requests/minute.
• Webhook management (create/update/delete) — 30 requests/minute.

Pagination

List endpoints are cursor-paginated. A page looks like:

{
  "results": [ /* ... */ ],
  "next_cursor": "MjAyNi0wNy0wMVQ...",
  "has_more": true
}

• Pass limit to set the page size (default 50, max 100).
• When has_more is true, pass the returned next_cursor as the cursor query parameter to fetch the next page.
• Stop when has_more is false (next_cursor is null).
• A malformed cursor returns 400 invalid_cursor.

curl "https://chatonio.com/api/v1/conversations/?limit=100&cursor=MjAyNi0wNy..." \
  -H "Authorization: Bearer csk_live_your_key_here"