Errors
Two shapes, and how to tell them apart
Errors come back in one of two shapes depending on how far into the system your request got. Handle both — a client that parses only one will throw on the other exactly when something is already going wrong.
Rejected at the door — authentication and the API's own rate limiting:
{ "message": "invalid API key" }
Rejected by the endpoint — anything the API itself refused:
{
"code": 3,
"message": "limit must be at most 100, got 5000",
"details": []
}
The safe way to read both: use the HTTP status for control flow, and message
for the human. Both shapes always carry message, so logging
response.message works either way.
One case carries neither shape: a request stopped by the per-IP edge ceiling never
reaches the API, and comes back as the gateway's HTML error page. That is the one
place a message lookup throws — see what you will not get.
The code in the second shape is not the HTTP status. It is a gRPC status
code, because these endpoints are generated from service definitions — 3 is
invalid argument, 5 is not found. If you are branching on anything, branch on
the HTTP status.
When a request body is refused
A write whose body breaks a rule answers 400 with the second shape, and
details says what to fix: a google.rpc.BadRequest with one entry per
problem, naming the field by its path and saying why. Every rule the body itself
breaks is in the same answer. On an update, whether the cargo and options fit
the stored inquiry is checked once the body passes, so that can come back in a
second answer.
{
"code": 3,
"message": "request is invalid",
"details": [
{
"@type": "type.googleapis.com/google.rpc.BadRequest",
"field_violations": [
{ "field": "origin", "description": "value is required", "reason": "", "localized_message": null },
{ "field": "incoterms", "description": "must contain at least 1 item(s)", "reason": "", "localized_message": null },
{ "field": "lcl.components[0].weight", "description": "must be greater than 0", "reason": "", "localized_message": null }
]
}
]
}
Read field and description. A path counts list entries from zero, so
lcl.components[0] is the first component you sent.
A key the request does not have — a typo, or a field only Cargoplot sets, such as
status — is refused before any rule runs, so it carries no field violations.
message names the key instead:
{
"code": 3,
"message": "proto: (line 9:19): unknown field \"carrier\"",
"details": []
}
Status codes
| Status | Meaning | Worth retrying? |
|---|---|---|
400 | Your request was malformed — a bad limit, both cursors at once, an unknown enum value (glossary), a request body that breaks a rule, a malformed Idempotency-Key, or a write made through an AI assistant without one | No. Fix the request. |
401 | Missing, malformed or revoked token | No. See authentication. |
403 | The record is yours to see but not to change through the API — a delivery order or an arrival notice, which can be downloaded but not uploaded into; or prices that are not available to your account, where Cargoplot can help | No. |
404 | No such record, or not one you can see | No. |
405 | The path exists, but not for the method you used: a DELETE on a read endpoint, or a POST to one. A form-encoded POST is not served as the GET, and X-HTTP-Method-Override has no effect. The body is the second shape with code 12. The Allow header lists the methods the path accepts, such as Allow: GET, PATCH; the reference lists the methods of each path it covers | No. Use a method from the Allow header. |
409 | The record can no longer be changed — an inquiry whose quote has been accepted, the cargo-ready date of a shipment whose cargo has been picked up, or the client references of a shipment that is completed or cancelled. Booking a quote answers it when the inquiry already has a booked quote, when it is cancelled, when the quote is no longer open to booking, or when a drop-off location on it is unresolved. An upload without a slot answers it too, when several open slots of the type match, or when the insurance certificate slot is already filled; the answer names the slot ids. A reply in a customs conversation that does not exist yet answers it too. A request with the same Idempotency-Key as one still being processed answers it too, with Retry-After | No. Upload into the slot you mean, book the quote the message names, or wait until the customs conversation holds a message. The one exception is an Idempotency-Key still in flight: retry after Retry-After. |
413 | The request declares a body over the largest one the API reads. It is refused before the body is read, with {"message": "request body too large"}: the first shape above. A body sent without a length and over the limit answers 400 instead, as it is read. Above 64 MiB the edge in front of the API answers with its own HTML page, like the per-IP 429 | No. Send a smaller file. |
422 | The Idempotency-Key was sent before with a different request | No. Use a new key for a new request. |
429 | Rate limit exceeded — your token's quota, or the per-IP edge ceiling | Yes. After Retry-After if the response carries one, otherwise back off. |
500 | Something broke on our side | Yes, with backoff. Report it if it persists. |
503 | No healthy backend behind the edge, or an Idempotency-Key that could not be checked | Yes, with backoff. |
A 404 covers both "this does not exist" and "this exists but is not yours". That
is intentional: distinguishing them would let anyone confirm whether a reference
belongs to another company.
Retrying
Retry 429, 500 and 503. Do not retry 400, 401, 404, 405, 409 or 422 —
the same request will fail the same way, and a loop around a 401 is how a token
ends up locked out of a log file rather than fixed. The one exception is a 409 for
an Idempotency-Key still in flight: retry that after
Retry-After.
A retry that reaches us twice is not a second booking. Booking a quote our team
prepared a second time answers 200 with Idempotent-Replayed: true and the
booking you already have. Booking a price worked out for the inquiry a second
time answers 409 naming the quote the first booking made, because nothing
records which price a stored copy came from — see
booking the same thing twice — unless both
bookings carry the same Idempotency-Key.
For 429, wait the Retry-After seconds when the response carries one. The
edge ceiling does not send the API's headers, so back off exponentially there
instead. For 500 and 503, do the same and give up after a handful of attempts
rather than hammering a service that is already unwell.
Every read is safe to repeat, and so is every write except a message post:
- A repeated upload does not store twice. A file whose bytes are already in
the slot, or on the shipment for an upload without a slot, is answered with
that slot and
Idempotent-Replayed: true. See documents. - A retried create does not create twice. An identical create from your
organization within ten minutes is answered with the inquiry the first one
made, and
Idempotent-Replayed: truesays so. See inquiries. - An update or a cancel repeated leaves the inquiry as the first one did, and a repeated cargo-ready date or list of client references leaves the shipment as it was.
- A delete repeated answers
404, because the inquiry is already gone from your view. After a delete that timed out, a404on the retry means it succeeded. - A repeated message post is posted twice, unless it carries an
Idempotency-Key: the same text sent twice can be meant twice, so nothing de-duplicates it. Each copy notifies the people who are notified of a message. See messages. Marking a conversation read can be repeated.
Idempotency keys
The rules above recognise a retry from what it asks for. To be certain that a
retry takes effect once, whatever the endpoint, send an Idempotency-Key header
with the write — any POST, PATCH or DELETE:
POST /v1/inquiry
Idempotency-Key: 3f2b8c1e-6a4d-4e0b-9c57-1d2e8f0a4b6c
The key is yours to choose: 1 to 255 printable ASCII characters without spaces,
or the same as a quoted string ("3f2b…"). A fresh UUID per write you mean to
make is a good choice. Send the same key again only for a retry of that write.
- The same key with the same request within 24 hours runs nothing. The answer
is the first one's status and body, with
Idempotent-Replayed: true. That includes booking a worked-out price, which answers409on a retry without a key. - The same request means the same method, path, query and body, byte for byte. Re-serialising the body with other whitespace or key order, or naming a shipment by its reference where the first request used its id, makes it another request.
- The same key with another request answers
422, and runs nothing. - The same key while the first request is still being processed answers
409withRetry-After. Retry after that many seconds to get the first one's answer. - A request that failed — any answer other than a
2xx— does not keep its key, so you can fix it and send it again with the same key. - A malformed key answers
400, and so does a key from a user who belongs to no organization. - A key that cannot be checked answers
503, and runs nothing: retry it. - Keys are kept per user for 24 hours. A colleague's request with the same key is a request of its own.
Without the header, nothing changes: the retries described above are recognised
as before. A write made through an AI assistant on your behalf always carries a
key, and is refused with 400 without one.
What you will not get
- No HTML from the API. Everything the API itself refuses is JSON. The
exception is the per-IP edge ceiling: it is enforced in front of the API and
serves the gateway's own HTML error page, so do not assume a
429body is parseable — check theRateLimit-*headers instead. - No stack traces or internal detail. A
500tells you it failed, not what our database was doing. If you need to know, quote the time and the endpoint in a support request. - No partial pages. A list request either returns a page or an error. It will not return half the records and an error field.