Rate limits & quotas
Contents 26 pages
Two different things limit you, and they behave differently.
A burst limiter caps how fast one key may call — about 120 requests per minute. Treat the figure as approximate. It exists so a runaway loop cannot flood us; it is not a budget and you should never plan against it.
Three daily meters are the budget. They count per organization, reset at
00:00 UTC, and are shared by every key your organization holds. Quotes
requested in the web app can count against the same quotes meter, and MCP
calls count like any other.
| Meter | Counts | Default |
|---|---|---|
requests |
Every call whose key is accepted — including ones then refused for scope or validation. | 10,000 / day |
quotes |
Every lane rated — a 25-lane bulk call counts 25. | 1,000 / day |
bookings |
Every booking we accepted. A refused one is returned. | 100 / day |
Your organization may have different ceilings. ShipEasy can also give a single
key a requests or bookings ceiling of its own — email
support@shipeasyco.com to ask for one or change it. A key's ceiling counts
that key's usage only, applies on top of the organization's ceiling
rather than instead of it, and can never be set above the organization's. A call
is refused when either one is spent. GET /account reports, per meter,
whichever of the two ceilings leaves the calling key less room.
POST /shipments/{id}/refresh-status has its own limit of 60 per hour for
your organization (all keys together), because each call spends a real carrier
lookup. Like the burst limiter, treat it as approximate. Its Retry-After can be
up to an hour. The daily meters still apply on top.
POST /bookings also allows about 10 attempts a minute. Past that you get
429 rate_limit_exceeded without Retry-After; wait a minute. The bookings
unit is handed back.
A Shopify store's key is metered on the store's own counters, and its quotes share one daily budget with its Shopify app.
When the meter charges#
requestscharges before the work. It is an abuse ceiling, so the refusal has to come first.quotescharges before rating, and gives back a lane that rated nothing. Quoting reads your remaining budget, charges the lanes that fit into it, and only then asks the carriers. A lane that returns no rates is handed back, so it costs nothing. A lane past the budget is not rated at all.bookingscharges before the work, and gives the unit back on a refusal. Charging first is what keeps two simultaneous bookings from both squeezing under the last unit of the day. A booking we refuse — a declined card or a changed price — is handed back, so it costs you nothing. The one exception is502 payment_outcome_unknown: the card may have been charged, so the unit stays spent.
A booking refused because the budget is spent returns daily_quota_exceeded
and never touches your card.
Rate-limit headers#
Sent on every response once your key has been accepted.
RateLimit-Limit: 10000
RateLimit-Remaining: 9588
RateLimit-Reset: 41209
RateLimit-Policy: 10000;w=86400
X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9588
X-RateLimit-Reset: 1755043200
ShipEasy-Request-Id: req_3f9c2a71d04b8e65Both families are sent: the unprefixed RateLimit-* names are the IETF draft,
and X-RateLimit-* is what most client libraries read today. They report the
same numbers with one difference — RateLimit-Reset is seconds from now,
X-RateLimit-Reset is a Unix timestamp.
The numbers describe the requests meter, which is the one every call touches.
For the quote and booking budgets, read GET /account.
Retry-After (seconds) comes with a 429 from the burst limiter, the
requests meter and the refresh limit. Honour it. A 429 for the quotes or
bookings budget carries none — read usage.*.resets_at on GET /account.
Reading a 429#
{
"error": {
"type": "rate_limit",
"code": "daily_quota_exceeded",
"message": "The daily quota for that operation — the organization's, or this API key's own — is spent. It resets at 00:00 UTC.",
"request_id": "req_3f9c2a71d04b8e65",
"doc_url": "/developers/errors#daily_quota_exceeded"
}
}Two codes, and they call for different responses:
rate_limit_exceeded— you are going too fast. Back off and continue.Retry-Afteris usually seconds; after the refresh limit it can be up to an hour, and the booking limit sends none — wait a minute.daily_quota_exceeded— the budget is spent. Waiting will not help until 00:00 UTC. If this happens routinely, ask support to raise the ceiling rather than sleeping through it.
Staying inside the limits#
Poll no more often than once a minute. /ping and /account both report
min_poll_interval_seconds. Faster polling costs you requests for no new
information — carrier status does not change every second.
Use the change feed, not a full sweep. ?updated_since=… returns only what
moved since you last looked. See pagination. A nightly
full list of 4,000 shipments is 160 requests; the same coverage as a change feed
is usually one or two.
Batch your quotes. POST /quotes/bulk rates up to 25 lanes in one request.
It costs the same on the quotes meter — one per lane — but a twenty-fifth of
the requests.
Cache what does not move. On /account, carriers, shipping and
booking change rarely; usage changes with every call. Your origins change
even less.
Watch it in the web app. Your owners and admins see each day of the last 7 or 30 against these limits, which key or AI app spent what, and every refusal it got, under AI & API → Usage & problems. The days are the same UTC days the meters count.
If our counter is slow#
Every call is counted. If we cannot record a call against your meters, we
refuse it with 503 api_unavailable and a Retry-After of a few seconds, and
nothing is run, charged or booked. Retry it like any 503.
That includes quotes: a lane is counted before any carrier is asked, so a quote
we could not count was never rated and never appears in GET /quotes. A
POST /quotes/bulk we cannot count, or whose remaining budget we cannot read,
is refused whole with nothing rated; retry it with the same Idempotency-Key.
GET /account reads the counters without adding to them. If the read cannot
finish in time, the response still comes back with usage.degraded: true:
requests is this call's own count, and quotes and bookings read as nothing
used, a floor rather than a fact.