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:

1. Check the request_id: Always include the request_id from the response header or body when contacting support.
2. Validate Input Types: Ensure that boolean, integer, and string types match the API schema.
3. Inspect Headers: Ensure Content-Type: application/json is set for all POST, PUT, and PATCH requests.
4. 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"}'