Status Codes & Error Handling

Overview

The Supervised AI testing API uses standard HTTP response codes to indicate the success or failure of an API request.

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

Error Response Structure

When an error occurs, the API returns a structured JSON response to help you identify and resolve the issue.

{
  "status": "error",
  "error": {
    "code": "invalid_request_error",
    "message": "The 'model_id' parameter is required.",
    "param": "model_id",
    "type": "validation_error"
  }
}

Response Attributes

HTTP Status Code Mapping

The following table summarizes the status codes used across the Supervised AI platform:

Specific Error Scenarios

Validation Errors (400/422)

Occurs when the payload structure is correct, but the values provided are invalid for the specific endpoint.

Example Response:

{
  "status": "error",
  "error": {
    "code": "value_out_of_range",
    "message": "Confidence threshold must be between 0.0 and 1.0.",
    "param": "threshold"
  }
}

Authentication Errors (401)

Occurs if the Authorization header is missing, malformed, or contains an expired API key.

Example Response:

{
  "status": "error",
  "error": {
    "code": "invalid_api_key",
    "message": "The API key provided is invalid or has been revoked."
  }
}

Rate Limiting (429)

To ensure platform stability, we enforce rate limits on API calls. When you exceed these limits, the API returns a 429 status code.

Best Practice: Check the Retry-After header in the response to determine how many seconds to wait before retrying the request.

Handling Errors in Code

We recommend implementing a global error handler or middleware to catch non-2xx responses.

// Example using Fetch API
const response = await fetch('https://api.supervised.ai/v1/tests', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${API_KEY}` },
  body: JSON.stringify(payload)
});

if (!response.ok) {
  const errorData = await response.json();
  console.error(`Error [${response.status}]: ${errorData.error.message}`);
  
  // Specific logic for rate limiting
  if (response.status === 429) {
    const retryAfter = response.headers.get('Retry-After');
    // Implement exponential backoff or wait based on retryAfter
  }
}