Cargoplot APICargoplot API
API docs
OpenAPI spec

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:

json
{ "message": "invalid API key" }

Rejected by the endpoint — anything the API itself refused:

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

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

json
{
  "code": 3,
  "message": "proto: (line 9:19): unknown field \"carrier\"",
  "details": []
}

Status codes

StatusMeaningWorth retrying?
400Your 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 oneNo. Fix the request.
401Missing, malformed or revoked tokenNo. See authentication.
403The 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 helpNo.
404No such record, or not one you can seeNo.
405The 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 coversNo. Use a method from the Allow header.
409The 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-AfterNo. 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.
413The 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 429No. Send a smaller file.
422The Idempotency-Key was sent before with a different requestNo. Use a new key for a new request.
429Rate limit exceeded — your token's quota, or the per-IP edge ceilingYes. After Retry-After if the response carries one, otherwise back off.
500Something broke on our sideYes, with backoff. Report it if it persists.
503No healthy backend behind the edge, or an Idempotency-Key that could not be checkedYes, 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: true says 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, a 404 on 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:

http
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 answers 409 on 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 409 with Retry-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 429 body is parseable — check the RateLimit-* headers instead.
  • No stack traces or internal detail. A 500 tells 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.