Error Codes & Meanings

Error Response Structure

All error responses from the Testing API follow a consistent JSON format. This allows client applications to programmatically handle failures using the code field while displaying the message to end-users.

Error Object Schema:

| Field | Type | Description | | :--- | :--- | :--- | | success | boolean | Always false for error responses. | | error.code | string | A unique, machine-readable string identifying the error type. | | error.message | string | A human-readable description of the error. | | error.details | object | (Optional) Additional context, such as validation failure specifics. |

Example Error Payload:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request body contains invalid parameters.",
    "details": {
      "test_id": "Field is required",
      "priority": "Must be one of: low, medium, high"
    }
  }
}

HTTP Status Codes

The Testing API uses standard HTTP status codes to indicate the general outcome of an API request.

| Status Code | Meaning | Description | | :--- | :--- | :--- | | 400 | Bad Request | The request was unacceptable, often due to missing a required parameter. | | 401 | Unauthorized | No valid API key provided. | | 403 | Forbidden | The API key does not have permissions to perform the request. | | 404 | Not Found | The requested resource (e.g., Test Case, Suite) does not exist. | | 429 | Too Many Requests | You have hit the rate limit for your current plan. | | 500, 502, 503 | Server Errors | Something went wrong on the Supervised AI platform side. |

Application Error Codes

While the HTTP status code provides a high-level category, the error.code string provides specific context regarding the failure.

Authentication & Authorization

| Code | HTTP Status | Description | | :--- | :--- | :--- | | AUTH_EXPIRED | 401 | The provided session or token has expired. | | INVALID_API_KEY | 401 | The API key is missing or incorrectly formatted. | | INSUFFICIENT_PERMISSIONS | 403 | Your account role does not allow this specific action (e.g., deleting a shared test suite). |

Validation & Logic

| Code | HTTP Status | Description | | :--- | :--- | :--- | | VALIDATION_ERROR | 400 | One or more input fields failed validation. See details for field-specific errors. | | DUPLICATE_RESOURCE | 409 | An object with the same unique identifier (like a Test Case Name) already exists. | | MALFORMED_JSON | 400 | The JSON payload in the request body is syntactically incorrect. |

Resource Management

| Code | HTTP Status | Description | | :--- | :--- | :--- | | RESOURCE_NOT_FOUND | 404 | The requested ID does not match any record in our database. | | PROJECT_ARCHIVED | 403 | Action denied because the parent project has been archived. |

AI Platform Specifics

| Code | HTTP Status | Description | | :--- | :--- | :--- | | MODEL_TIMEOUT | 504 | The AI model failed to respond within the allotted testing window. | | INSUFFICIENT_QUOTA | 429 | You have exhausted the testing credits or token limit for your billing cycle. | | UPSTREAM_SERVICE_ERROR | 502 | A third-party service required for the test (e.g., LLM provider) returned an error. |

Handling Errors in Code

When integrating with the Testing API, it is recommended to first check the HTTP status code, then switch based on the application code for granular logic.

Example (Node.js/Axios):

try {
  const response = await testingApi.post('/v1/run-test', payload);
} catch (err) {
  if (err.response) {
    const { code, message } = err.response.data.error;

    switch (code) {
      case 'INSUFFICIENT_QUOTA':
        console.error("Upgrade required:", message);
        break;
      case 'VALIDATION_ERROR':
        console.error("Check your inputs:", err.response.data.error.details);
        break;
      default:
        console.error(`Error (${code}): ${message}`);
    }
  }
}