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. |
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
extensionsfield to help identify the cause and appropriate resolution.