API errors

Understand and resolve errors returned by the Zonos GraphQL API.

GraphQL

The Zonos API returns two types of errors: HTTP status codes for transport-level failures, and GraphQL errors for application-level issues. Most errors are GraphQL errors that include a classification in the extensions field to help identify the cause and appropriate resolution.

HTTP status codes

HTTP errors are returned when a request cannot be processed at the transport level.

Status code↕	Meaning↕
400	Invalid argument / bad request — the request contains invalid input.
401	Unauthorized — no valid credentials were provided.
404	Not found — the requested resource does not exist.
409	Resource conflict — the request conflicts with the current state of a resource.
412	Failed precondition — a required condition was not met before processing.
422	Unprocessable entity — the request body is structurally valid but contains invalid values.
429	Rate limited — too many requests in a short period. Use exponential backoff and retry.
500	Internal server error — an unexpected server-side failure occurred. Retry; contact support if persistent.
503	Service unavailable — the service is temporarily offline. Retry after a short delay.
504	Timeout — the server did not receive a response in time. Retry the request.

GraphQL error format

Application-level errors are returned as a list in the errors field of the response body. Each error includes a message, the path of the operation that failed, and an extensions object with the error type and request ID.

1{

2 "errors": [

3 {

4 "message": "Description of the error",

5 "path": [

6 "landedCostCalculate"

7 ],

8 "extensions": {

9 "errorType": "BAD_REQUEST",

10 "requestId": "req_abc123"

11 }

12 }

13 ]

14}

Error classifications

The extensions.errorType field indicates the category of the error and the recommended action.

Classification↕	HTTP equivalent↕	Meaning↕	Action↕
`BAD_REQUEST`	400	Invalid input or request parameters.	Fix the request — check required fields, formats, and values.
`NOT_FOUND`	404	A referenced resource does not exist.	Verify IDs, codes, and that required defaults are configured.
`UNAVAILABLE`	503	The requested service or option is not available for this route.	Try a different method, service level, or destination.
`PERMISSION_DENIED`	401 / 403	Authentication or authorization failure.	Check credentials and account permissions.
`FAILED_PRECONDITION`	412	A required configuration or setup condition was not met.	Check org settings or contact support.
`INTERNAL`	500	An unexpected server-side failure occurred.	Retry the request; contact support if the issue persists.
`UNKNOWN`	500	An unexpected error with no further classification.	Verify request format; contact support if the issue persists.

Book a demo

API errors

HTTP status codes

GraphQL error format

Error classifications

Was this page helpful?