Error Handling

The Testing API utilizes standard HTTP response codes to indicate the outcome of API requests. Responses in the 2xx range indicate success, 4xx range codes indicate client-side errors (e.g., invalid parameters or authentication failures), and 5xx range codes indicate server-side issues.

Error Response Schema

All error responses return a consistent JSON object, allowing your application to parse and handle errors programmatically.

Example Error Payload:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request body contains invalid fields.",
    "details": {
      "model_id": "Field is required",
      "temperature": "Must be a float between 0 and 1"
    }
  }
}

HTTP Status Code Mappings

The following table describes the status codes the Testing API returns and the scenarios in which they occur.

Error Codes

While the HTTP status code provides a high-level category, the error.code string provides specific context. Common codes include:

INVALID_AUTH_TOKEN: The provided token is expired or incorrectly formatted.
RESOURCE_LOCKED: The resource is currently being processed and cannot be modified.
LIMIT_EXCEEDED: You have reached the quota for your current subscription tier.
UPSTREAM_TIMEOUT: The AI model provider failed to respond within the allowed timeframe.

Handling Errors in Clients

When integrating with the Testing API, it is recommended to catch error responses and use the code field for conditional logic.

try {
  const response = await api.get('/v1/tests/123');
} catch (error) {
  if (error.response.status === 404) {
    console.error("Test case not found. Redirecting user...");
  } else if (error.response.data.error.code === 'VALIDATION_ERROR') {
    highlightFormFields(error.response.data.error.details);
  }
}