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, is not bound to an integration, or its integration is inactive.
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. Nothing else in the error body tells the three causes apart, so the two rarer ones are the place to read message:

• No integration. The token resolves but isn’t bound to any integration, and message says so.
• Inactive integration. The integration was switched off in Zentail. message says the integration is inactive. For a signal you can match on, call the status route of the API that refused you: GET /v2/inventory/status or GET /v2/shipping/status. Both still answer, and their integration_active check fails.

Only the inventory and shipping routes answer an inactive integration with this 403. They refuse it here:

• Inventory: GET /v2/inventory, POST /v2/inventory and GET /v2/inventory/warehouses.
• Shipping: only POST /v2/shipping/fulfillment_orders/acknowledge. Every other shipping route keeps working: you can still ship orders, reject them, confirm the cancellations Zentail asks for, and raise alerts. Because you can’t acknowledge, a cancellation of an order you haven’t acknowledged never reaches you. Before you ship such an order, check that it is still in need_to_ship.

Your code can’t clear this 403, and retrying won’t help. Stop making the refused calls with that token, and ask the seller to contact Zentail support at [email protected]. Support can reactivate the integration. The same token then works again, with no new authorization needed. Keep polling the status route, and resume the refused calls once its integration_active check passes.

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. The one exception is the inactive-integration 403: the same token works again once support reactivates the integration, so resume when the status route’s integration_active check passes.
• 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.