Errors

A v2 error answers an HTTP status and a google.rpc.Status body. The body’s code is a gRPC status code, not the HTTP status, and message says what went wrong. Branch on the HTTP status, and log message for anything you don’t handle automatically. v1 errors use different bodies and a few different status meanings; see the aside at the end.

The v2 body

{
  "code": 7,
  "message": "missing required scope \"inventory:self\"",
  "details": []
}

• code is an integer gRPC code. The table below maps each one to its HTTP status.
• message is a human-readable string. Don’t match on its exact wording.
• details is an array of typed objects, each carrying an @type. It is often empty.

Status codes

HTTP	code	When
400	3	An argument failed validation, such as a malformed timestamp or a cursor the route can’t read.
401	16	The request carried no token.
403	7	The token is valid but lacks the scope the service needs, or it is not bound to an integration.
404	5	The thing addressed, or the route itself, does not exist.
429	8	Resource exhausted, such as a rate limit. See Throttle limits.
500	13	An unhandled error on our side. Code 2 (unknown) also answers 500.
503	14	A service the call depends on is unavailable. Transient.

Scope failures are the common 403. The scoped services name the missing scope in message, as in the example above. See Scopes. The rarer cause — a token that resolves but isn’t bound to any integration — is the one place worth reading message for: it says so explicitly, and no other field tells the two apart.

What to retry

• Retry with backoff: 429 and 503. Both are transient.
• Do not retry unchanged: 400, 401, 403 and 404. The request or the credential has to change first.
• Retry once, then escalate: 500. If it repeats, send us the time, the route and the message.

Legacy (v1)

Most v1 errors answer an array of messages, and an unhandled one answers a single string under a differently spelled key:

{
  "errorCode": 400,
  "errorMessages": ["pageLength: abc is not a valid integer."],
  "referenceId": "6c1f2f3a-9b4d-4d1e-8b27-1e0b0a5a1f77"
}

{
  "errorCode": 500,
  "errorMessage": "Call to a member function getId() on null",
  "referenceId": "6c1f2f3a-9b4d-4d1e-8b27-1e0b0a5a1f77"
}

A rate-limited v1 request answers from the edge, before the application runs:

{ "errorCode": "429", "errorMessage": "Rate Limit Exceeded" }

Read both errorMessages and errorMessage. A 400 returns one entry per failed argument. A 429’s errorCode is the string "429", and it has no referenceId.

referenceId is what to quote to support. It is a UUID generated once per request and written to our logs, so we can find your exact request with it.

Two v1 status codes differ from v2:

• 401 means the token is valid but its account is deactivated. Only reactivating the account fixes it.
• 403 means the token is unknown or inactive, or it lacks the scopes the endpoint needs.

A v1 503 means the authentication service could not be reached. Check a v1 404’s message before assuming a bad path:

Message	Means
Invalid Version	The version segment of the URL is not v1.
Endpoint not found.	No endpoint matches that method and path.
Company not found	The token resolved to an account we cannot reach, usually an offboarded one. It is a 404 on purpose, so retry-on-5xx clients stop.
SKU not found.	The SKU in the request is not in the catalog.
NextToken '...' not valid for this endpoint.	The paging token has expired, or another endpoint issued it. See Pagination.
Cancellation Reason is invalid. It has to be in the list of valid reasons provided at developer.zentail.com	The cancel request’s reason isn’t in the channel’s list. See Valid cancellation reasons per channel.