Cargoplot APICargoplot API
API docs
OpenAPI spec

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.

LimitValueCounted
Reads per token500 / 60sper API instance
Writes per token60 / 60sper API instance
Document uploads per token10 / 60sper API instance
Quote requests per token30 / 60sper API instance
Largest upload15 MiBper file, before base64
Counted peruserthe identity your token belongs to
Requests per IP at the edge500 / 60sper gateway instance, all traffic from the address
Request timeout60sper request
Page size, default / maximum50 / 100per list request

Reading your allowance

Every rate-limited response — not only the rejections — carries three headers:

HeaderMeaning
RateLimit-LimitRequests allowed per window
RateLimit-RemainingHow many you have left
RateLimit-ResetSeconds 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:

json
{ "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.

json
{ "message": "API write rate limit exceeded" }

The upload allowance answers the same, with a message of its own:

json
{ "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:

json
{ "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-Remaining costs 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 429 spends 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.