Rate limits
You may make 500 requests per minute. Every response tells you where you stand, so a well-behaved client never has to find the ceiling by hitting it.
Writes — a create, an update, a cancel, a delete: anything other than GET,
HEAD and OPTIONS — can have an allowance of their own, listed as Writes per
token in the table below. When they do, a write is counted only against that
allowance and a read only against the one above, so running out of one leaves the
other untouched. When the table says writes are counted as requests, a write costs
what a GET does. Either way, a retried create that is
answered as a replay is still a request, and still
counts.
The quote endpoints have an allowance of their own, listed as Quote
requests per token and published as quote_rate_limit in /api-info.json.
Every quote endpoint, listing an inquiry's quotes, reading a quote's details or
its sailings and booking one, is counted only against it, not against the allowances above, so a
client that works with quotes often cannot use up the allowance of its other
reads and writes, and the other way round. While it is not enabled, these
requests are counted as reads or writes, whichever they are.
Uploading a document is a write, and has an allowance of its own, listed as Document uploads per token. Both uploads, into a slot and without one, are counted only against it, so a burst of files cannot use up the write allowance and changing a shipment keeps working. While it is not enabled, uploads are counted as writes. The table also shows the largest file an upload accepts.
The numbers on this page are read from the running API when you load it, not written into the page. If they disagree with something you were told elsewhere, believe this page.
The per-IP figure describes the edge in front of api.cargoplot.com — see
two limits, not one for what that counts.
| Limit | Value | Counted |
|---|---|---|
| Reads per token | 500 / 60s | per API instance |
| Writes per token | 60 / 60s | per API instance |
| Document uploads per token | 10 / 60s | per API instance |
| Quote requests per token | 30 / 60s | per API instance |
| Largest upload | 15 MiB | per file, before base64 |
| Counted per | user | the identity your token belongs to |
| Requests per IP at the edge | 500 / 60s | per gateway instance, all traffic from the address |
| Request timeout | 60s | per request |
| Page size, default / maximum | 50 / 100 | per list request |
Reading your allowance
Every rate-limited response — not only the rejections — carries three headers:
| Header | Meaning |
|---|---|
RateLimit-Limit | Requests allowed per window |
RateLimit-Remaining | How many you have left |
RateLimit-Reset | Seconds until your full allowance is back |
The headers describe the allowance the request was counted against: the upload allowance for an upload, when uploads have one, the write allowance for a write, when writes have one, the quote allowance for a request to a quote endpoint, when the quote endpoints have one, and the shared one otherwise.
RateLimit-Reset counts seconds from now, not a timestamp. That is
deliberate: a client with a skewed clock still reads it correctly.
If you see none of these headers, you are not being counted against this limit — either limiting is switched off in the environment you are talking to, the request was not authenticated with an access token, or the edge answered before the API ever saw it.
When you go over
The per-identity limit answers 429 Too Many Requests:
{ "message": "API rate limit exceeded" }
with a Retry-After header in seconds. Wait that long and try again.
Running out of the write allowance answers the same way, with its own message, so you can tell which one you hit. Your reads keep working in the meantime, and so do your uploads while writes have run out, as long as uploads have an allowance of their own.
{ "message": "API write rate limit exceeded" }
The upload allowance answers the same, with a message of its own:
{ "message": "API upload rate limit exceeded" }
The quote allowance answers the same, with a message of its own. Your other reads keep working in the meantime:
{ "message": "API quote rate limit exceeded" }
The per-IP edge ceiling described below answers 429 as well, but it is enforced
in front of the API, so it carries no RateLimit-* headers and returns the
gateway's HTML error page rather than JSON. Branch on whether the headers are
present, not on the status alone — see errors.
Retry-After and RateLimit-Reset answer different questions, and both are
sent. Retry-After is when may I retry this request; RateLimit-Reset is when
is my whole allowance back. If you are backing off from a 429, use
Retry-After.
Counted per instance, not per cluster
Both limits are enforced by whichever instance handles the request, and there is more than one of each. The practical consequences:
- The effective ceiling is higher than the number above — how much higher depends on how many instances are running, which changes.
- It is not evenly applied. Two requests a second apart may be counted by different instances, so you can be throttled slightly earlier or later than the arithmetic suggests.
Design against the published number and treat anything above it as luck. If you need a hard guarantee for a scheduled job, pace it below the limit rather than racing to it.
Two limits, not one
The per-identity limit above is the precise one: it counts your token's requests.
There is also a coarser per-IP ceiling at the edge, in front of the API. It is a
flood protection rather than a quota, and it counts every request from your
address regardless of which token it carries — so anything else calling from the
same outbound IP shares the ceiling with you. Tripping it answers 429 as well,
but a bare one, with no RateLimit-* headers, because the request never reached
the part of the system that issues them. That absence is how you tell the two
apart: a 429 carrying RateLimit-* is your token's own quota, a 429 carrying
none is the edge.
api.cargoplot.com is fronted by its own edge, so only API traffic counts
against this ceiling — not anything else Cargoplot serves.
Pacing yourself
- Read the headers.
RateLimit-Remainingcosts nothing and removes all guesswork. - Ask for bigger pages, not more pages. One request for 100 records beats five for twenty.
- Poll on a schedule, not in a loop. If you are watching for shipment changes, a fixed interval is both cheaper and more predictable than a tight poll.
- Back off when told to. Retrying immediately after a
429spends your next window's allowance on requests that will also be refused.
A request also has 60 seconds to complete before the server gives up on it. Reaching that on a read means something is wrong on our side, not yours — it is worth reporting.