Error Handling Patterns
Error Response Schema
The testing-api follows a standardized error response format to ensure consistency across all endpoints in the Supervised AI platform. When a request fails, the API returns a structured JSON payload containing a machine-readable code and a human-readable message.
Error Object Structure
| Field | Type | Description |
| :--- | :--- | :--- |
| error.code | string | A constant string identifier for the error type (e.g., VALIDATION_ERROR). |
| error.message | string | A descriptive message explaining why the error occurred. |
| error.details | object | (Optional) Additional context, such as field-specific validation failures. |
| request_id | string | A unique identifier for the request, used for debugging and support. |
Example Error Payload:
{
"error": {
"code": "INVALID_PARAMETER",
"message": "The 'model_id' field is required.",
"details": {
"field": "model_id",
"reason": "missing"
}
},
"request_id": "req_8823af910c"
}
HTTP Status Codes
The API uses standard HTTP status codes to indicate the success or failure of an API request.
| Status Code | Type | Description |
| :--- | :--- | :--- |
| 400 | Bad Request | The request was unacceptable, often due to missing parameters. |
| 401 | Unauthorized | No valid API key provided. |
| 403 | Forbidden | The API key does not have permissions to perform the request. |
| 404 | Not Found | The requested resource (e.g., a specific test run) does not exist. |
| 422 | Unprocessable Entity | The syntax is correct, but the request failed business logic (e.g., incompatible model types). |
| 429 | Too Many Requests | Rate limit exceeded. |
| 500 | Server Error | Something went wrong on the Supervised AI platform's end. |
Best Practices for Error Handling
1. Robust Retries
For 429 (Too Many Requests) or 5xx errors, it is recommended to implement a retry mechanism with exponential backoff. Avoid immediate retries to prevent further overwhelming the service.
2. Logging Request IDs
Always log the request_id returned in the error payload. If you need to contact Supervised AI support regarding a failed test or API call, providing the request_id significantly accelerates the troubleshooting process.
3. Handling Validation Errors
When receiving a 400 or 422 error, inspect the details object. The API provides specific feedback on which parameters failed validation, allowing for programmatic correction before re-attempting the call.
// Example: Conditional handling in JavaScript
if (response.status === 422) {
const body = await response.json();
if (body.error.code === 'INCOMPATIBLE_DATASET') {
// Logic to handle specific dataset mismatch
console.error(`Dataset error: ${body.error.message}`);
}
}
4. Graceful Degradation
In a testing environment, ensure that your integration handles 500 series errors gracefully. If the testing-api is temporarily unavailable, your CI/CD pipeline should be configured to either fail-safe or alert the team without blocking critical deployment paths, depending on your organization's risk profile.