Error Messages 🚨

The API uses standard HTTP status codes. For validation errors (422), the message array in the response tells you exactly which fields are missing or invalid.

Status	Cause	How to fix it
`400 Bad Request`	The body is not valid JSON ("Unexpected token" / invalid syntax).	Validate your JSON — look for trailing commas, missing quotes or comments (`//`), which JSON doesn't allow.
`403 Forbidden`	The `X-API-KEY` header is missing, the key is invalid or belongs to the other environment, or you have no access to the requested resource.	Send your key in the `X-API-KEY` header and check it. Sandbox and production use different keys — see Test and Production System.
`404 Not Found`	The URL or the requested object (e.g. an order ID) doesn't exist.	Check the base URL, the path and any IDs in it.
`409 Conflict`	The request conflicts with the current state, e.g. an order that can no longer be cancelled or labels that aren't ready yet. Also returned if the API key isn't linked to a customer account.	Read the `message` in the response. Contact us if it persists.
`422 Unprocessable Entity`	The JSON is valid, but fields are missing or contain invalid values.	Read the `message` array in the response and correct the fields listed there.
`429 Too Many Requests`	Rate limit exceeded — e.g. more than 20 orders per minute, or the same order sent more than 3 times within 5 minutes.	Slow down and retry later.
`500 Internal Server Error`	An unexpected error, caused by the request or on our side.	Contact us and include your request body or cURL command.
`502 Bad Gateway`	A problem on our side. By the time you see it, we're already aware of it and working on it.	Try again later. You're always welcome to contact us.

Example: validation error (422)

A request with an unsupported country code returns:

{
  "statusCode": 422,
  "message": [
    "shipper.address.countryCode must be one of the following values: AL, AT, BE, BG, CH, CZ, DE, DK, EE, ES, FI, FR, GB, GR, HR, HU, IE, IT, LI, LT, LU, LV, NL, NO, SI, PL, PT, RS, RO, SE, SK, TR"
  ],
  "error": "Unprocessable Entity"
}

Contacting support

For any error, contact the Cargoboard API team at [email protected] — we reply quickly. To help us find the cause fast, please include:

the environment (sandbox or production) and the endpoint you called
the time of the request
your request body or cURL command — without your API key
the complete error response