When integrating with the IZIX API, understanding how to handle errors effectively is crucial. The IZIX API utilizes standard HTTP response codes to signify the outcome of API requests. Here's what each range of response codes generally indicates:
- 2xx codes denote success—the API request was successfully received, understood, and processed.
- 4xx codes signify client errors—these errors occur because of an issue with the request, such as missing parameters or authentication failures.
- 5xx codes indicate server errors—these suggest that IZIX’s servers encountered an issue and could not fulfill the request.
HTTP Status Code Summary
| Code | Status Text | Description |
|---|---|---|
| 200 | OK | The request was successfully processed. |
| 400 | Bad Request | The request could not be understood due to missing parameters. |
| 401 | Unauthorized | No valid API key was provided. |
| 402 | Request Failed | The request was valid but could not be completed as requested. |
| 403 | Forbidden | The API key lacks permissions to perform the request. |
| 404 | Not Found | The specified resource could not be found. |
| 409 | Conflict | There was a conflict with another request (e.g., duplicate submissions). |
| 429 | Too Many Requests | Request rate exceeded. Recommended strategy: exponential backoff. |
| 500 | Server Error | A generic error occurred on the server. |
| 502 | Bad Gateway | The server received an invalid response from the upstream server. |
| 503 | Service Unavailable | The server is temporarily unavailable, usually due to maintenance or loading. |
| 504 | Gateway Timeout | The server did not receive a timely response from an upstream server. |
Error Attributes
When an error occurs, the API response will include the following attributes to aid in diagnosing and handling the error:
- event_id: An identifier for the event, which can be correlated with IZIX's monitoring tools.
- code: A specific programmatic error code from IZIX that details the error type.
- error: A short string identifier for the error, suitable for programmatic handling.
- status: The HTTP status code of the error, which is also reflected in the HTTP status header of the response.
- details: A human-readable explanation providing more insight into the nature of the error.
By using this structured format for error reporting, developers can more easily implement robust error handling and debugging strategies, ensuring a smoother integration process with the IZIX API.