Skip to content

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#

  • requests charges before the work. It is an abuse ceiling, so the refusal has to come first.
  • quotes charges 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.
  • bookings charges 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 is 502 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_3f9c2a71d04b8e65

Both 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#

JSON
{
	"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-After is 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.