Pagination and retries

Pagination

List endpoints return items, has_more and next_cursor. Pass next_cursor as cursor to fetch the next page; limit is 1 to 100.

curl "https://utopia-payments.com/api/v1/payments?limit=50" \
  -H "Authorization: Bearer $UTOPIA_API_KEY"

# → { "items": [...], "has_more": true, "next_cursor": "eyJ0Ijoi…" }

curl "https://utopia-payments.com/api/v1/payments?limit=50&cursor=eyJ0Ijoi…" \
  -H "Authorization: Bearer $UTOPIA_API_KEY"

Idempotency

Send an Idempotency-Key header with POST requests. If a request times out, retry it with the same key: you get the first response back instead of a second checkout session. Keys are remembered for 24 hours. The libraries add one automatically.

Reusing a key with different parameters returns 422 IDEMPOTENCY_KEY_REUSED.

Override the automatically generated key when your application already has a stable operation id:

await utopia.checkoutSessions.create(params, { idempotencyKey: 'order-1001' });

$utopia->checkoutSessions->create($params, ['idempotency_key' => 'order-1001']);

Rate limits

Each key can make 240 requests per minute. Beyond that the API answers 429 RATE_LIMITED with a Retry-After header. The libraries wait and retry.