Pagination, limits, rate limits

This section describes how to paginate lists, maximum payload sizes, and how to respond to rate limiting. Staying within limits avoids 413 and 429 errors.

Cursor pagination

Lists return paged results with opaque cursor pagination. The cursor is an opaque token — do not parse or build it yourself; use the value returned by the API to fetch the next page.

• limit — items per page; default 50, maximum 200.
• cursor — next-page token; absence in the response means end of list.

# first page
curl "https://api.callbotagent.ai/api/v1/commerce/orders?limit=50" \
  -H "X-CBA-Key-Id: cba_test_••••••••"
# next page — use cursor from next_cursor in the previous response
curl "https://api.callbotagent.ai/api/v1/commerce/orders?limit=50&cursor=eyJvIjoxMjN9" \
  -H "X-CBA-Key-Id: cba_test_••••••••"

let cursor = null;
do {
  const url = new URL(`${baseUrl}/api/v1/commerce/orders`);
  url.searchParams.set('limit', '50');
  if (cursor) url.searchParams.set('cursor', cursor);
  const page = await (await fetch(url, { headers: signedHeaders(keyId) })).json();
  cursor = page.next_cursor; // absent → end of list
} while (cursor);

$cursor = null;
do {
    $query = ['limit' => 50] + ($cursor ? ['cursor' => $cursor] : []);
    $page = json_decode((string) $client->get('/api/v1/commerce/orders', ['query' => $query])->getBody(), true);
    $cursor = $page['next_cursor'] ?? null;
} while ($cursor);

Payload and resource limits

Exceeding body or batch size returns 413 payload_too_large — split large imports into smaller batches. For exports above 10,000 records, use pagination instead of synchronous export.

Rate limiting and Retry-After

When the request rate limit is exceeded, the API returns 429 rate_limited with a Retry-After header (seconds until retry). The same header accompanies 503 tenant_unavailable.

• Wait for Retry-After before retrying.
• Use exponential backoff with jitter when Retry-After is absent.
• For mutations, retry with the same Idempotency-Key — see Idempotency.
• Code meanings are in Errors.