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.

Reading your allowance

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

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.

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.

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.