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:

1. Check the Retry-After header (if provided) to see how long to wait.
2. Optimize your implementation to batch requests where possible.
3. 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:

1. Note down the request_id from the error response.
2. Contact the technical support team via the Supervised AI dashboard or email support@supervised.ai.