Error Codes & Handling

Error Response Format

The Testing API uses standard HTTP response codes to indicate the success or failure of an API request. In the event of an error, the response body is returned as a JSON object containing specific details to help you diagnose the issue.

Error Object Schema

Every error response follows a consistent structure:

Example Error Response:

{
  "error": {
    "code": "authentication_failed",
    "message": "The provided API key is invalid or has expired.",
    "request_id": "req_88291x01"
  }
}

Platform Error Codes

The following table lists the common status codes and platform-specific error strings you may encounter.

Best Practices for Error Handling

Implementing Retry Logic

When interacting with the Supervised AI platform, especially during high-concurrency testing, you may encounter 429 Rate Limit Exceeded or transient 5xx errors.

We recommend implementing Exponential Backoff with Jitter. This involves increasing the wait time between retries exponentially and adding a random "jitter" to prevent a thundering herd problem.

Retry Logic Pseudo-code:

import time
import random

def call_api_with_retry(request_func, max_retries=5):
    retry_count = 0
    while retry_count < max_retries:
        response = request_func()
        
        if response.status_code == 200:
            return response
        
        # Only retry on 429 or 5xx errors
        if response.status_code == 429 or response.status_code >= 500:
            wait_time = (2 ** retry_count) + random.uniform(0, 1)
            print(f"Error {response.status_code}. Retrying in {wait_time:.2f}s...")
            time.sleep(wait_time)
            retry_count += 1
        else:
            # For 400, 401, 403, 404 - do not retry
            raise Exception(f"API Error: {response.text}")
            
    raise Exception("Max retries exceeded")

Handling Rate Limits

When you receive a 429 error, check the HTTP response headers for more information:

X-RateLimit-Limit: The maximum number of requests allowed in a window.
X-RateLimit-Remaining: The number of requests left in the current window.
Retry-After: The number of seconds to wait before making a new request.

Logging for Debugging

Always log the request_id returned in the error response. If you need to contact Supervised AI support regarding a failed request, providing the request_id will significantly speed up the resolution process.