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

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

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.