Response Status Codes

Response Overview

The Supervised AI Testing API uses standard HTTP response codes to indicate the success or failure of an API request. In addition to HTTP status codes, the platform provides machine-readable sub-codes within the response body to help developers handle specific error scenarios programmatically.

In general:

• 2xx codes indicate success.
• 4xx codes indicate an error caused by the information provided (e.g., a required parameter was omitted, authentication failed, etc.).
• 5xx codes indicate an error with the Supervised AI platform servers.

Success Status Codes

| Code | Status | Description | | :--- | :--- | :--- | | 200 | OK | The request was successful and the response body contains the requested data. | | 201 | Created | The request was successful and a new resource (e.g., a test suite or data point) has been created. | | 202 | Accepted | The request has been accepted for processing (typically for long-running AI model evaluations), but processing is not yet complete. | | 204 | No Content | The request was successful, but there is no representation to return (commonly used for DELETE operations). |

Error Status Codes

Client Errors (4xx)

| Code | Status | Description | | :--- | :--- | :--- | | 400 | Bad Request | The request was unacceptable, often due to missing a required parameter or invalid JSON. | | 401 | Unauthorized | No valid API key was provided. | | 403 | Forbidden | The API key does not have the required permissions for the endpoint. | | 404 | Not Found | The requested resource (test case, model ID, etc.) does not exist. | | 409 | Conflict | The request conflicts with the current state of the server (e.g., duplicate unique identifier). | | 422 | Unprocessable Entity | The request was well-formed but contains semantic errors (e.g., invalid model parameters). | | 429 | Too Many Requests | Too many requests hit the API too quickly. Please refer to our rate limiting guide. |

Server Errors (5xx)

| Code | Status | Description | | :--- | :--- | :--- | | 500 | Internal Server Error | Something went wrong on the Supervised AI end. | | 503 | Service Unavailable | The server is temporarily unable to handle the request, usually due to maintenance or high load. |

Platform-Specific Sub-codes

When a request results in an error, the response body includes a sub_code to provide granular detail. This is especially useful for handling AI-specific logic during testing.

| Sub-code | Description | Suggested Action | | :--- | :--- | :--- | | ERR_VAL_MISSING_FIELD | A required field in the JSON payload is missing. | Check the details field in the response for the missing key. | | ERR_AI_MODEL_TIMEOUT | The target model failed to respond within the testing window. | Increase the timeout parameter or retry the request. | | ERR_DATA_LIMIT_EXCEEDED | The test data payload exceeds the maximum allowed size. | Batch your testing data into smaller requests. | | ERR_AUTH_EXPIRED | The provided session token or API key has expired. | Refresh your credentials. | | ERR_MODEL_NOT_READY | The model is currently cold-starting or provisioning. | Wait and retry after the duration specified in retry-after. |

Error Response Format

All error responses follow a consistent JSON structure to simplify integration across different testing environments.

{
  "success": false,
  "error": {
    "status": 422,
    "code": "UNPROCESSABLE_ENTITY",
    "sub_code": "ERR_VAL_INVALID_FORMAT",
    "message": "The provided data format is not supported for this model type.",
    "details": {
      "field": "input_type",
      "expected": "text/plain",
      "received": "application/pdf"
    },
    "request_id": "req_8829104af2"
  }
}

Response Fields

• success: Always false for error responses.
• status: The HTTP status code (integer).
• code: A string representation of the HTTP status.
• sub_code: The platform-specific identifier for the error.
• message: A human-readable explanation of the error.
• details: (Optional) An object containing specific metadata about the failure (e.g., validation errors).
• request_id: A unique identifier for the request, useful for debugging with Supervised AI support.