Rate Limit Headers

This document specifies how the API meters requests: the limits that apply per API key, the headers every response carries so your client can pace itself, and what happens when a limit is exceeded. Limits protect a shared service; a well-behaved client that watches the headers will rarely see a 429.

The limits

Requests are metered per API key, in a rolling one-minute window

Class	Limit	Applies to
Read	600 requests per minute	`GET` requests
Write	120 requests per minute	`POST`, `PATCH`, `PUT`, `DELETE` requests
Referral submission	10 requests per minute	`POST /vet/referrals` (Veterinary and Pharmacy Endpoints)

Limits apply to the key, not to the network address: two systems sharing one key share one budget. If your integration outgrows these limits, contact support@aapawz.com before raising your request rate: a higher allowance can be set on your account where the use case supports it. Sustained traffic far above the limits, or traffic designed to evade metering, is misuse under the Developer Agreement.

The headers

Every response, successful or not, carries three headers

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 437
X-RateLimit-Reset: 1760463330

Header	Meaning
`X-RateLimit-Limit`	The limit for this request's class in the current window
`X-RateLimit-Remaining`	Requests remaining in the current window for that class
`X-RateLimit-Reset`	Unix time, in seconds, at which the current window resets

When X-RateLimit-Remaining approaches zero, slow down before you are stopped: finishing the window early and then bursting at its reset produces exactly the traffic shape metering exists to smooth. Bulk work such as price updates (Pricing Endpoints) should spread writes evenly rather than firing them all at a window boundary.

Exceeding a limit

When a limit is exceeded the API returns 429 with the standard error body (Error Codes) and a Retry-After header

HTTP/1.1 429 Too Many Requests
Retry-After: 12
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1760463330
Content-Type: application/json

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Retry after 12 seconds."
  }
}

On a 429

Wait at least the Retry-After interval. Retrying sooner counts toward the next window and fails again.
Resume at a reduced rate, and increase gradually. After repeated 429 responses, double your wait between attempts, up to a few minutes.
Do not open parallel retry loops from multiple workers: coordinate retries in one place.

Webhook deliveries from the Platform do not consume your request budget, and your replies to them are not metered (Webhook Event Schemas).

Client discipline

Watch X-RateLimit-Remaining continuously; treat it as the budget signal, not the 429.
Prefer events over polling. Subscribe to webhooks for orders, shipments, and payments instead of listing resources on a timer; when you must poll, poll one collection with a cursor (Pagination and Filtering (Pagination & Filtering)) at a modest interval.
Fetch collections in pages at the maximum page size rather than many small pages.
Cache slow-changing reads: categories, brand records, your own product records: on your side for minutes, not seconds.
Schedule bulk imports for steady throughput across the whole window.

Error Codes

Pagination & Filtering