Errors

Error format

Every error returns the same JSON object:

{
  "code": "invalid_argument",
  "msg": "product.barcode value does not match regex pattern `^([[:digit:]]{12,13}|)$`",
  "meta": { "argument": "product.barcode" }
}

codeenumrequired

Machine-readable error code. Use this in your error handling.

msgstringrequired

Human-readable message for logs. The wording can change.

metamap<string, string>

Extra details. Validation errors include argument, the path of the invalid field.

Check the code, not the HTTP status

Some codes share a status. 403 is used for both permission_denied and resource_exhausted, 404 for not_found and bad_route, and 409 for already_exists and aborted.

Codes

invalid_argument: HTTP: 400; A field is invalid or a value can't be parsed. Fix the request.
malformed: HTTP: 400; The body isn't valid JSON.
out_of_range: HTTP: 400; A value is outside the allowed range.
unauthenticated: HTTP: 401; The Authorization header is missing or malformed.
permission_denied: HTTP: 403; The API key isn't recognized or has been revoked.
resource_exhausted: HTTP: 403; You exceeded 200 requests per minute. Wait and retry.
not_found: HTTP: 404; No object with this ID exists on your account.
bad_route: HTTP: 404; The path is wrong, or the method isn't POST.
already_exists: HTTP: 409; An object with this ID already exists.
aborted: HTTP: 409; The request conflicted with another one. Retry.
failed_precondition: HTTP: 412; The object's current state doesn't allow this, for example cancelling a shipped order.
canceled: HTTP: 408; The request was cancelled.
deadline_exceeded: HTTP: 408; The request timed out. Retry with backoff.
unimplemented: HTTP: 501; The operation isn't available.
internal: HTTP: 500; Server error. Retry with backoff, and contact support if it continues.
unknown: HTTP: 500; Unknown server error.
unavailable: HTTP: 503; The service is temporarily unavailable. Retry with backoff.
data_loss: HTTP: 500; Data was lost. Contact support.

Code	HTTP	Meaning
`invalid_argument`	400	A field is invalid or a value can't be parsed. Fix the request.
`malformed`	400	The body isn't valid JSON.
`out_of_range`	400	A value is outside the allowed range.
`unauthenticated`	401	The `Authorization` header is missing or malformed.
`permission_denied`	403	The API key isn't recognized or has been revoked.
`resource_exhausted`	403	You exceeded 200 requests per minute. Wait and retry.
`not_found`	404	No object with this ID exists on your account.
`bad_route`	404	The path is wrong, or the method isn't `POST`.
`already_exists`	409	An object with this ID already exists.
`aborted`	409	The request conflicted with another one. Retry.
`failed_precondition`	412	The object's current state doesn't allow this, for example cancelling a shipped order.
`canceled`	408	The request was cancelled.
`deadline_exceeded`	408	The request timed out. Retry with backoff.
`unimplemented`	501	The operation isn't available.
`internal`	500	Server error. Retry with backoff, and contact support if it continues.
`unknown`	500	Unknown server error.
`unavailable`	503	The service is temporarily unavailable. Retry with backoff.
`data_loss`	500	Data was lost. Contact support.

Validation errors

Fields are validated before the request is processed. The message names the field and the rule it broke, and meta.argument contains the field path:

Missing required field

{
  "code": "invalid_argument",
  "msg": "order.shipping_address is required",
  "meta": { "argument": "order.shipping_address" }
}

Value doesn't match the pattern

{
  "code": "invalid_argument",
  "msg": "order.id value does not match regex pattern `^([[:alnum:]]{12}|)$`",
  "meta": { "argument": "order.id" }
}

Some checks run later and return no meta. Examples are an amount that can't be parsed, an unknown currency, or B2B instructions on an order that isn't B2B:

{ "code": "invalid_argument", "msg": "un-parseable amount '12,90 EUR'" }

Retrying

Code	Retry	How
`resource_exhausted`	Yes	Wait a few seconds. The limit uses a one-minute window.
`internal`, `unknown`, `unavailable`, `deadline_exceeded`, `canceled`	Yes	Exponential backoff with jitter, with a maximum number of attempts.
`aborted`	Yes	Retry right away.
`invalid_argument`, `malformed`, `out_of_range`	No	Fix the request.
`unauthenticated`, `permission_denied`	No	Fix the API key.
`not_found`, `bad_route`	No	Fix the ID or URL.
`already_exists`	No	If you're retrying a create with your own ID, the first attempt succeeded.
`failed_precondition`	No	Get the object again. Its state doesn't allow the operation.

Send your own IDs to retry creates safely

When you create an order, inbound shipment or return, send your own id. A retry then either succeeds or returns already_exists, and no duplicate is created. See Identifiers.

Email support@bigblue.io. Include the method name, the approximate time of the request and the error code. Bigblue logs each request with its integration, payload and response, so support can find it.

Error format

Codes

Validation errors

Retrying

Getting help

On this page