HTTP Status Codes
HTTP Status Codes
The Supervised AI Testing API uses standard HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g., a required parameter was missing, a validation error, etc.), and codes in the 5xx range indicate an error with Supervised AI's servers.
Success Codes
| Status Code | Description |
| :--- | :--- |
| 200 OK | The request was successful. The response body contains the requested data. |
| 201 Created | The request was successful and a new resource (e.g., a test suite or evaluation run) was created. |
| 204 No Content | The request was successful, but there is no representation to return (commonly used for DELETE operations). |
Client Error Codes
These errors typically require action from the developer to correct the request payload or authentication.
| Status Code | Description |
| :--- | :--- |
| 400 Bad Request | The request was unacceptable, often due to missing a required parameter or invalid syntax. |
| 401 Unauthorized | No valid API key provided. Ensure your Authorization header is correctly formatted. |
| 403 Forbidden | The API key does not have the required permissions to perform the action on the specific resource. |
| 404 Not Found | The requested resource (e.g., test_id) does not exist. |
| 409 Conflict | The request conflicts with the current state of the server (e.g., attempting to create a resource that already exists). |
| 422 Unprocessable Entity | The request was well-formed but contains semantic errors, such as a dataset failing schema validation for a specific AI model. |
| 429 Too Many Requests | Too many requests hit the API too quickly. We recommend an exponential backoff schedule. |
Example Error Response
When a 4xx error occurs, the response body will follow a consistent structure to help you debug:
{
"error": {
"code": "invalid_parameter",
"message": "The 'dataset_id' field is required to initiate a testing run.",
"param": "dataset_id",
"type": "validation_error"
}
}
Server Error Codes
| Status Code | Description |
| :--- | :--- |
| 500 Internal Server Error | Something went wrong on Supervised AI's end. |
| 502 Bad Gateway | The server, while acting as a gateway or proxy, received an invalid response from an upstream server. |
| 503 Service Unavailable | The server is temporarily unable to handle the request, usually due to maintenance or high load. |
Error Handling Best Practices
When integrating with the Testing API, it is recommended to implement specific logic for the following codes:
- 429 (Rate Limiting): Implement a retry mechanism with exponential backoff.
- 422 (Validation): Log the error message to identify which part of your testing metadata or payload does not conform to the Supervised AI schema.
- 5xx (Server Errors): These are rare but should be handled by alerting your internal system or retrying after a delay.