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,000 requests / minute
Partner integration	1,000 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

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.

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