Error Contracts

Error Response Schema

All failed requests in the testing-api return a standardized JSON object. This consistency allows client integrations to implement predictable error-handling logic across the Supervised AI platform.

The error payload follows this structure:

interface ErrorResponse {
  success: boolean;       // Always false for error responses
  error: {
    code: string;         // Domain-specific error string
    message: string;      // Human-readable description
    details?: any;        // Optional object containing field-specific errors
    trace_id: string;     // Unique identifier for log correlation
  };
}

Field Definitions

| Field | Type | Description | | :--- | :--- | :--- | | success | boolean | Indicates the outcome of the request. For errors, this is always false. | | error.code | string | A machine-readable, uppercase string used for programmatic branching (e.g., VALIDATION_ERROR). | | error.message | string | A clear, concise explanation of why the error occurred, suitable for developer debugging. | | error.details | object | (Optional) Additional context, such as a list of invalid fields in a form or specific constraints that were violated. | | error.trace_id | uuid | A unique ID generated for every request. Use this ID when reporting issues to the Supervised AI support team. |

Domain-Specific Error Codes

The following error codes are standardized across the testing API to help categorize failures:

Authentication & Authorization

| Code | Description | | :--- | :--- | | UNAUTHORIZED | The request lacks valid authentication credentials. | | FORBIDDEN | The authenticated user does not have permission to access the requested resource. | | TOKEN_EXPIRED | The provided session or API token has expired. |

Resource & Validation

| Code | Description | | :--- | :--- | | NOT_FOUND | The requested resource (e.g., a test case, model, or dataset) does not exist. | | VALIDATION_ERROR | The request body or parameters failed schema validation. | | CONFLICT | The request conflicts with the current state of the server (e.g., duplicate test name). |

AI Platform & Execution

| Code | Description | | :--- | :--- | | ENGINE_TIMEOUT | The AI inference or testing engine failed to respond within the allocated time. | | MODEL_NOT_READY | The requested model is still in a provisioning or training state. | | INSUFFICIENT_QUOTA | The organization has exceeded its testing execution limits. |

Usage Examples

1. Validation Error (HTTP 400)

Returned when the input data does not match the required schema for a test suite.

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request payload contains invalid fields.",
    "details": {
      "test_type": "Field is required",
      "iterations": "Must be a positive integer"
    },
    "trace_id": "req-99af-1234-bcde"
  }
}

2. Not Found Error (HTTP 404)

Returned when requesting a specific test ID that does not exist in the database.

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Test execution with ID 'exec_001' could not be found.",
    "trace_id": "req-77bb-5678-fghi"
  }
}

3. Engine Failure (HTTP 503)

Returned when the underlying Supervised AI inference engine is temporarily unavailable.

{
  "success": false,
  "error": {
    "code": "ENGINE_TIMEOUT",
    "message": "The AI inference engine failed to process the request. Please retry later.",
    "trace_id": "req-11cc-9012-jklm"
  }
}

Client-Side Handling

When integrating with the testing-api, it is recommended to handle errors based on the code rather than the message, as messages may change for clarity while codes remain stable.

try {
  const response = await apiClient.runTest(testData);
} catch (err) {
  const { code, trace_id } = err.response.data.error;

  if (code === 'VALIDATION_ERROR') {
    // Logic to highlight UI fields
    showFieldErrors(err.response.data.error.details);
  } else if (code === 'INSUFFICIENT_QUOTA') {
    // Logic to prompt for upgrade
    showUpgradeModal();
  } else {
    console.error(`Unexpected error [${trace_id}]: ${code}`);
  }
}