Error Handling Patterns

Error Response Schema

The testing-api follows a standardized error response format to ensure consistency across all endpoints in the Supervised AI platform. When a request fails, the API returns a structured JSON payload containing a machine-readable code and a human-readable message.

Error Object Structure

Example Error Payload:

{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "The 'model_id' field is required.",
    "details": {
      "field": "model_id",
      "reason": "missing"
    }
  },
  "request_id": "req_8823af910c"
}

HTTP Status Codes

The API uses standard HTTP status codes to indicate the success or failure of an API request.

Best Practices for Error Handling

1. Robust Retries

For 429 (Too Many Requests) or 5xx errors, it is recommended to implement a retry mechanism with exponential backoff. Avoid immediate retries to prevent further overwhelming the service.

2. Logging Request IDs

Always log the request_id returned in the error payload. If you need to contact Supervised AI support regarding a failed test or API call, providing the request_id significantly accelerates the troubleshooting process.

3. Handling Validation Errors

When receiving a 400 or 422 error, inspect the details object. The API provides specific feedback on which parameters failed validation, allowing for programmatic correction before re-attempting the call.

// Example: Conditional handling in JavaScript
if (response.status === 422) {
  const body = await response.json();
  if (body.error.code === 'INCOMPATIBLE_DATASET') {
    // Logic to handle specific dataset mismatch
    console.error(`Dataset error: ${body.error.message}`);
  }
}

4. Graceful Degradation

In a testing environment, ensure that your integration handles 500 series errors gracefully. If the testing-api is temporarily unavailable, your CI/CD pipeline should be configured to either fail-safe or alert the team without blocking critical deployment paths, depending on your organization's risk profile.