Limits and Safeguards#

Rate limiting#

A rate limit applies to all API requests to prevent excessive load from any single integrator.

Context	Limit
Standard	1,600 requests / minute
Partner integration	1,600 requests / minute per merchant

If you exceed the limit, the API returns a 429 status with a rate_limit_exceeded error. These requests are safe to retry. Check the response headers to know when you can resume:

ratelimit-limit: 1000
ratelimit-remaining: 163
ratelimit-reset: Thu, 03 May 2018 16:00:00 GMT

If you're making a large batch of requests, think of 1,000 requests/minute as a performance target — hitting it means completing the task as fast as possible.

Timeouts#

Type	Duration	Notes
Request timeout	29 seconds	A single request cannot exceed this duration.
Keepalive timeout	10 minutes	Persistent connections with no requests for this period are closed.

Idempotency keys#

Some requests are dangerous to retry without protection. When creating resources, pass an Idempotency-Key header to ensure the key can only be used for one successful request:

Idempotency-Key: a1b2c3d4-e5f6-7890-abcd-ef1234567890

If a resource already exists for that key, the API returns a 409 idempotent_creation_conflict error with a links.conflicting_resource_id pointing to the existing resource.

Double-charge risk

Always use idempotency keys when creating payments or mandates. A network timeout that causes you to retry without one can result in the same payment being taken twice.

Guidelines:

Keys must be no longer than 128 characters
Use UUIDv4 — any non-repeating unique identifier is sufficient
Keys are honoured for at least 30 days
Our API libraries generate idempotency keys automatically

What's next#

Responses and Errors

Understand 429 rate_limit_exceeded and 409 idempotent_creation_conflict in context.

Learn more

Data Conventions

Date formats, cursor pagination, and other request conventions.

Learn more

Was this helpful?

Support Dashboard