Skip to main content

Rate limits

Rate limits are applied per client (your client id), per minute. They protect the API, and the address and quote endpoints in particular, which call Google.

Limits​

Each group of requests has its own limit, counted separately.

RequestsBusinessPlatform
POST /quotes30 a minute300 a minute
POST /addresses30 a minute300 a minute
Any GET600 a minute600 a minute
Other writes (POST /deliveries, book, ready, cancel, confirm, PATCH, DELETE)120 a minute120 a minute
POST /wallet/fund10 a minute10 a minute
POST /webhooks/test10 a minute10 a minute
Sandbox endpoints (/sandbox/...)60 a minute60 a minute

The token endpoint, POST /oauth/token, allows 60 requests a minute per client. Cache your access token (it lasts an hour) instead of fetching one per request.

If your volume needs more, email support@getreeds.co with your client id and the volume you expect.

Test mode and Live mode have their own credentials, so each has its own count.

Headers​

Responses carry your current standing:

HeaderDescription
X-RateLimit-LimitRequests allowed in the current window, for this request's group
X-RateLimit-RemainingRequests left in the current window
X-RateLimit-ResetUnix time (seconds) when the window resets

When you go over​

Over the limit, the API returns 429 with the code RATE_LIMITED and a Retry-After header, the number of seconds to wait.

Response 429
HTTP/1.1 429 Too Many Requests
Retry-After: 12
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 0
Response 429
{
  "status": "failed",
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests",
    "doc_url": "https://developer.getreeds.co/errors/RATE_LIMITED"
  }
}

A 429 releases the idempotency key, so wait and retry with the same key.

RATE_LIMITED also covers the account's daily allowance for address lookups and pricing (saving, updating and confirming addresses, fresh quotes, and creating deliveries all ask Google). Once it is used up, those requests get 429 RATE_LIMITED with a message that says so, and Retry-After counts down to midnight, Lagos time. Reused quotes and saved addresses don't count. Email support@getreeds.co if your account needs more.

When Reeds is busy​

When Reeds is overloaded it sheds load rather than keep you waiting: any request, the token endpoint included, can get 503 with a Retry-After header, and nothing was done. The API answers SERVICE_UNAVAILABLE in the usual failure envelope; POST /oauth/token answers { "error": "temporarily_unavailable" }. Wait the Retry-After seconds, then send the same request again, with the same idempotency key.

Backoff advice​

  • Wait for Retry-After when it is present, on a 429 or a 503. Otherwise wait 1, 2, 4, 8 seconds, with a little random jitter, and give up after a few tries.
  • Slow down before you hit the limit: watch X-RateLimit-Remaining.
  • Quote once per checkout, not on every keystroke or page view. A quote lasts 24 hours.
  • Save addresses once with POST /addresses and reuse the ids.
  • Listen to webhooks instead of polling deliveries.

Next steps​