Error Code Registry
Error Response Format
All API errors follow a consistent format to help you identify and resolve issues programmatically. When an error occurs, the API returns a standard HTTP status code along with a JSON response body.
{
"error": {
"code": "ERROR_CODE_STRING",
"message": "A human-readable description of the error.",
"details": {
"field": "Optional specific details about the failure (e.g., validation errors)."
},
"request_id": "req_12345abcde"
}
}
Client-Side Errors (4xx)
These errors indicate a problem with the request sent to the API, such as missing parameters or authentication failures.
400 - Bad Request
| Code | Description | Troubleshooting |
| :--- | :--- | :--- |
| INVALID_PARAMETER | One or more parameters in the request are invalid or malformed. | Check the details field to identify the specific parameter and required data type. |
| MISSING_REQUIRED_FIELD | A mandatory field is missing from the payload. | Ensure your JSON body contains all required keys documented in the endpoint specification. |
| MALFORMED_JSON | The request body could not be parsed as valid JSON. | Validate your JSON syntax before sending the request. |
401 - Unauthorized
| Code | Description | Troubleshooting |
| :--- | :--- | :--- |
| AUTHENTICATION_FAILED | The provided API key or token is invalid. | Verify that your Authorization header is correctly formatted as Bearer <YOUR_TOKEN>. |
| TOKEN_EXPIRED | The session or access token has expired. | Generate a new access token using your credentials. |
403 - Forbidden
| Code | Description | Troubleshooting |
| :--- | :--- | :--- |
| INSUFFICIENT_PERMISSIONS | Your account does not have the required scope to access this resource. | Contact your administrator to verify your user role or API key permissions. |
| ACCESS_DENIED | The specific resource (e.g., a Test Suite) is restricted. | Ensure you are targeting a resource that belongs to your workspace. |
404 - Not Found
| Code | Description | Troubleshooting |
| :--- | :--- | :--- |
| RESOURCE_NOT_FOUND | The requested endpoint or resource ID does not exist. | Double-check the URL path and the ID (e.g., test_id) provided in the request. |
429 - Too Many Requests
| Code | Description | Troubleshooting |
| :--- | :--- | :--- |
| RATE_LIMIT_EXCEEDED | You have surpassed the allowed number of requests in a given timeframe. | Implement exponential backoff in your application. Check your subscription tier for rate limit thresholds. |
Server-Side Errors (5xx)
These errors indicate an issue within the Supervised AI platform infrastructure.
500 - Internal Server Error
| Code | Description | Troubleshooting |
| :--- | :--- | :--- |
| INTERNAL_ERROR | An unexpected error occurred on our end. | Note the request_id and contact support if the issue persists. |
| PROCESSING_FAILED | The AI model failed to process the testing request. | This may be temporary. Retry the request after a short interval. |
503 - Service Unavailable
| Code | Description | Troubleshooting |
| :--- | :--- | :--- |
| SERVICE_MAINTENANCE | The API is temporarily down for scheduled maintenance. | Check the official Supervised AI status page for uptime information. |
Troubleshooting Workflow
If you encounter an error not explicitly listed above, follow these steps:
- Check the
request_id: Always include therequest_idfrom the response header or body when contacting support. - Validate Input Types: Ensure that boolean, integer, and string types match the API schema.
- Inspect Headers: Ensure
Content-Type: application/jsonis set for allPOST,PUT, andPATCHrequests. - Test with cURL: Isolate the issue by running a basic cURL command to see if the error persists outside of your application code.
curl -X POST https://api.supervised.ai/v1/testing/run \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"test_suite_id": "ts_01"}'