Errors and rate limits

Response envelopes

Products share a small set of shapes. Read the envelope before the payload.

• TrackingMCP and the SchedulesMCP public surface wrap success in { "ok": true, ... }.
• AirCargoMCP and FreightRatesMCP return the payload under { "data": ... }.
• LoadingMCP returns { "ok": true, "plan": { ... } }.

On a bad request, the API is explicit rather than silent. TrackingMCP even suggests a fix:

{
  "ok": false,
  "message": "That number fails the ISO check digit, which almost always means one digit is off. Did you mean MEDU1234562?"
}

FreightRatesMCP uses a structured error object:

{ "error": { "code": "not_found", "message": "No rate for that lane yet." } }

Status codes

Code	Meaning
200	Success.
400	The request is malformed, or a required parameter is missing.
401	The key is missing or not recognised.
404	The reference resolved to nothing, or the lane has no data yet.
405	Wrong method. FreightRatesMCP is GET only.
429	You are over the rate limit. Back off and retry.

Error codes you will see in the FreightRatesMCP envelope include missing_key, invalid_request, not_found, method_not_allowed and server_error.

Rate limits and usage

Responses carry usage headers so you can watch your budget without a second call. Read them, and when you see 429, back off with a short exponential delay before retrying. Public endpoints are limited per IP; keyed endpoints are limited per account and plan.

Handling it well

• Treat any non-2xx as a typed outcome, not a crash. Branch on the code.
• Log the message. It is written to be read by a human on your side.
• Do not hammer a 404. A reference that fails the check digit will keep failing until it is corrected.