Errors

RFC 9457 application/problem+json with a machine-readable code and a hint.

Every non-2xx response has the content type application/problem+json (RFC 9457) and this shape:

JSON

{
  "type": "https://developers.gocubic.io/errors/invalid-api-key",
  "title": "Invalid API key",
  "status": 401,
  "code": "invalid_api_key",
  "detail": "The key in the Authorization header is not recognised or was revoked.",
  "hint": "Send 'Authorization: Bearer <key>'. Create a key at https://app.gocubic.io/settings/api-keys."
}

Field	Meaning
`type`	URI of this error's section on this page.
`title`	Short summary.
`status`	The HTTP status code, repeated.
`code`	Stable, machine-readable. Branch on this.
`detail`	What went wrong with this request.
`hint`	How to fix the request.
`parameter`	The offending query parameter. Only on `invalid_parameter`.

Error codes

`code`	HTTP status	Cause	Fix
`missing_api_key`	401	No `Authorization` header, or it is not in the `Bearer <key>` form.	Send `Authorization: Bearer $CUBIC_API_KEY`. Check the environment variable is set in the process that makes the request.
`invalid_api_key`	401	The key is mistyped, truncated, or was revoked.	Do not retry with the same key. Ask the account owner to create a new key at https://app.gocubic.io/settings/api-keys.
`insufficient_scope`	403	The key was issued without the scope the endpoint requires. Every key created today can read shipments.	Do not retry with the same key. Every key can read shipments today; contact Cubic if you need more.
`shipment_not_found`	404	No shipment has that reference on the account the key belongs to. Shipments of other accounts return the same error.	Check the reference. To find a shipment by any other identifier use `GET /v1/shipments?search=`.
`quote_not_found`	404	The shipment was booked without a quote.	Do not retry. Read the shipment's invoices instead.
`invalid_parameter`	400	A query parameter has a value that is out of range, malformed, or not an allowed enum value.	Read `parameter` to see which one, and `hint` for the allowed values. Correct the request; do not retry unchanged.
`invalid_cursor`	400	The `cursor` value was altered, or is reused with different filters than the request that produced it.	Restart from the first page without `cursor`. Never build or modify cursors.
`rate_limited`	429	More than 60 requests in one minute on this key.	Wait `Retry-After` seconds, then retry the same request.
`invalid_request`	400	The request is malformed in a way no more specific code covers. `status` carries the exact 4xx status.	Compare the request with the API reference. Do not retry it unchanged.
`not_found`	404	The path is not part of the API.	Check the path and method against the API reference.
`internal_error`	500	A fault on the Cubic side.	Retry with exponential backoff. If it persists, contact Cubic.
`service_unavailable`	503	Cubic is deploying a new version of the API.	Wait `Retry-After` seconds, then retry the same request.

What to retry

Status	Retry?
400, 401, 403, 404	No. Fix the request using `hint`.
429	Yes, after `Retry-After` seconds. See Rate limits.
500	Yes, with exponential backoff.
503	Yes, after `Retry-After` seconds. The API is restarting for a deployment.

Examples

`missing_api_key`

JSON

{
  "type": "https://developers.gocubic.io/errors/missing-api-key",
  "title": "Missing API key",
  "status": 401,
  "code": "missing_api_key",
  "detail": "The request has no 'Authorization: Bearer <key>' header.",
  "hint": "Send 'Authorization: Bearer <key>'. Create a key at https://app.gocubic.io/settings/api-keys."
}

`invalid_api_key`

JSON

{
  "type": "https://developers.gocubic.io/errors/invalid-api-key",
  "title": "Invalid API key",
  "status": 401,
  "code": "invalid_api_key",
  "detail": "The key in the Authorization header is not recognised or was revoked.",
  "hint": "Send 'Authorization: Bearer <key>'. Create a key at https://app.gocubic.io/settings/api-keys."
}

`insufficient_scope`

JSON

{
  "type": "https://developers.gocubic.io/errors/insufficient-scope",
  "title": "Insufficient scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The key is valid but was not issued with the scope this endpoint needs.",
  "hint": "Every key can read shipments today; contact Cubic if you need more."
}

`shipment_not_found`

JSON

{
  "type": "https://developers.gocubic.io/errors/shipment-not-found",
  "title": "Shipment not found",
  "status": 404,
  "code": "shipment_not_found",
  "detail": "No shipment with reference 'QB99999' exists on this account.",
  "hint": "Check the reference (for example 'QB10293'). To look a shipment up by PO number, container, master bill or FBA ID, call GET /v1/shipments?search=<value>."
}

`quote_not_found`

JSON

{
  "type": "https://developers.gocubic.io/errors/quote-not-found",
  "title": "Quote not found",
  "status": 404,
  "code": "quote_not_found",
  "detail": "Shipment 'QB10293' has no quote.",
  "hint": "Do not retry. The shipment was booked without a quote; its invoices are at GET /v1/shipments/<reference>/invoices."
}

`invalid_parameter`

JSON

{
  "type": "https://developers.gocubic.io/errors/invalid-parameter",
  "title": "Invalid parameter",
  "status": 400,
  "code": "invalid_parameter",
  "detail": "'Shipped' is not a valid value for 'status'.",
  "hint": "Use one of: Active, Delivered, Cancelled. Repeat the parameter to filter by several statuses.",
  "parameter": "status"
}

`invalid_cursor`

JSON

{
  "type": "https://developers.gocubic.io/errors/invalid-cursor",
  "title": "Invalid cursor",
  "status": 400,
  "code": "invalid_cursor",
  "detail": "The cursor is malformed or was issued for a different set of filters.",
  "hint": "Restart pagination: repeat the request without 'cursor', then follow 'nextCursor' from each response."
}

`rate_limited`

JSON

{
  "type": "https://developers.gocubic.io/errors/rate-limited",
  "title": "Rate limit exceeded",
  "status": 429,
  "code": "rate_limited",
  "detail": "This key has made more than 60 requests in the last minute.",
  "hint": "Wait the number of seconds in the 'Retry-After' header, then retry the same request."
}

`invalid_request`

JSON

{
  "type": "https://developers.gocubic.io/errors/invalid-request",
  "title": "Invalid request",
  "status": 400,
  "code": "invalid_request",
  "detail": "The request could not be understood.",
  "hint": "Check the method, path, query parameters and body against the API reference. Do not retry unchanged."
}

`not_found`

JSON

{
  "type": "https://developers.gocubic.io/errors/not-found",
  "title": "Not found",
  "status": 404,
  "code": "not_found",
  "detail": "Nothing exists at this path.",
  "hint": "Check the path and method against the API reference. Do not retry unchanged."
}

`internal_error`

JSON

{
  "type": "https://developers.gocubic.io/errors/internal-error",
  "title": "Internal error",
  "status": 500,
  "code": "internal_error",
  "detail": "An unexpected error occurred while handling the request.",
  "hint": "Retry with exponential backoff. The request itself is not the problem."
}

`service_unavailable`

JSON

{
  "type": "https://developers.gocubic.io/errors/service-unavailable",
  "title": "Service unavailable",
  "status": 503,
  "code": "service_unavailable",
  "detail": "The API is restarting for a deployment and is not taking requests.",
  "hint": "Wait the number of seconds in the 'Retry-After' header, then retry the same request."
}