Configure API error handling
ZTZenoti Docs Team Updated March 7, 2026 2 min readHow-to
All Zenoti API responses use standard HTTP status codes and return errors in a consistent JSON format. Implementing proper error handling in your integration ensures your application can identify, log, and recover from API errors.
Before you begin
- You need a valid API key or access token. See Set up API authentication.
- You should be familiar with standard HTTP status codes.
Permission: Manage API Keys, Manage Apps, and Manage Automation (under Administrator) -- Required to create backend applications and generate API keys.
How Zenoti API responses work
All Zenoti API responses are returned in JSON format. The response includes an error field that is null for successful requests and contains error details for failed requests.
Successful response
A successful response returns HTTP status 200 and the error field is null:
{
"data": { ... },
"error": null
}
Error response
An error response returns the appropriate HTTP status code and the error field contains a code and description:
{
"error": {
"code": 1001,
"description": "Invalid request parameters"
}
}
HTTP status code categories
| Status code | Category | Meaning |
|---|---|---|
| 200 | Success | The request completed successfully |
| 4XX | Client error | The request contains an error (invalid parameters, missing authentication, unauthorized access, resource not found) |
| 422 | Validation error | The request parameters are invalid (for example, page size exceeds 100) |
| 429 | Rate limit exceeded | You have exceeded the rate limit of 60 calls per minute |
| 5XX | Server error | An unexpected error occurred on the Zenoti server |
| 503 | Service unavailable | Typically caused by an unexpected spike in API traffic; service usually restores within approximately 5 minutes |
Steps
Implement error handling
- Check the HTTP status code for every API response. Handle 2XX responses as successful and all other status codes as errors.
- Parse the error object from the response body. Extract the
codeanddescriptionfields for logging and troubleshooting. - Implement retry logic for transient errors. For 429 (rate limit) and 503 (service unavailable) errors, implement exponential backoff with retries. See Configure API rate limits for retry strategies.
- Log error details including the HTTP status code, error code, description, endpoint called, and timestamp. This information is essential for debugging integration issues.
- Handle authentication errors by refreshing expired tokens or renewing expired API keys. A 401 response typically indicates an expired or invalid credential.
Tips
- Always check the
errorfield in the response body, even for 200 responses, to catch any application-level errors. - Implement a circuit breaker pattern for repeated 5XX errors to prevent overwhelming a struggling service.
- For 503 errors, wait approximately 5 minutes before retrying, as these typically resolve on their own.
- Contact Zenoti support if you consistently receive unexplained errors. See the Zenoti APIs FAQ for common error scenarios.
Was this article helpful?
Your feedback helps us improve our documentation.