Error Codes & Troubleshooting
Error Response Format
The Testing API uses a standardized JSON format for all error responses. When a request fails, the API returns an appropriate HTTP status code along with a detailed error object to help you diagnose the issue.
{
"success": false,
"error": {
"code": "ERROR_CODE_STRING",
"message": "A human-readable explanation of the error.",
"request_id": "req_8829103ac2",
"details": {
"field": "Optional metadata or validation constraints"
}
}
}
Error Object Fields
| Field | Type | Description |
| :--- | :--- | :--- |
| success | boolean | Always false for error responses. |
| error.code | string | A machine-readable string identifying the error type. |
| error.message | string | A brief description of why the error occurred. |
| error.request_id | string | A unique identifier for the request, useful for support queries. |
| error.details | object | (Optional) Contextual information, such as validation errors. |
Standard Error Codes
The following table lists the common error codes encountered when interacting with the Supervised AI Testing API.
| HTTP Status | Error Code | Description | Resolution |
| :--- | :--- | :--- | :--- |
| 400 | INVALID_REQUEST | The request body is malformed or missing required fields. | Check your JSON syntax and ensure all required parameters are present. |
| 401 | UNAUTHORIZED | Authentication failed or was not provided. | Verify that your Authorization header contains a valid API key. |
| 403 | INSUFFICIENT_PERMISSIONS | Your API key does not have access to this specific resource. | Ensure your account has the necessary tier or role for this action. |
| 404 | RESOURCE_NOT_FOUND | The requested resource (e.g., test case, model ID) does not exist. | Verify the ID in your request URL. |
| 415 | UNSUPPORTED_MEDIA_TYPE | The Content-Type header is missing or incorrect. | Ensure your header is set to application/json. |
| 429 | RATE_LIMIT_EXCEEDED | Too many requests sent in a short period. | Implement exponential backoff or reduce the frequency of your calls. |
| 500 | INTERNAL_SERVER_ERROR | An unexpected error occurred on our side. | Wait a few minutes and retry. If the error persists, contact support with the request_id. |
Troubleshooting Guide
Authentication Issues
If you receive a 401 Unauthorized error:
- Ensure the API key is passed in the headers as:
Authorization: Bearer <YOUR_API_KEY>. - Check if your API key has expired or been revoked in the Supervised AI dashboard.
- Ensure there are no leading or trailing spaces in the token string.
Validation Errors
If you receive a 400 Invalid Request error, check the details field in the response. It usually contains specific information about which field failed validation:
"details": {
"model_id": "Field is required",
"temperature": "Value must be between 0 and 1"
}
Rate Limiting
The Testing API enforces rate limits to ensure stability. If you receive 429 Rate Limit Exceeded:
- Check the
Retry-Afterheader (if provided) to see how long to wait. - Optimize your implementation to batch requests where possible.
- Contact the Supervised AI team if your testing workflow requires higher throughput.
Connection Timeouts
If you experience intermittent timeouts or 503 Service Unavailable errors:
- Verify your network connectivity and firewall settings.
- Ensure you are using the correct base URL for the testing environment.
- Check the [Supervised AI Status Page] (if available) for scheduled maintenance or outages.
Support Contact
If you encounter an error that is not documented here or require further assistance:
- Note down the
request_idfrom the error response. - Contact the technical support team via the Supervised AI dashboard or email
support@supervised.ai.