Error Reference

Overview

This reference covers all error types returned by the Adaptive API. Adaptive provides detailed, structured error responses to help you diagnose and resolve issues quickly. Key Features:

Type-safe errors with consistent JSON structure
Provider failure insights for fallback scenarios
Request tracking with unique request IDs
Recovery guidance for each error type

Quick Reference

Error Type	HTTP Code	Description	Recovery Strategy
`authentication_error`	401	Invalid or missing API key	Check API key and headers
`invalid_request_error`	400	Malformed request	Validate request format
`fallback_failed`	503	All providers failed	Retry with backoff
`model_registry_error`	404/503	Model lookup failed	Check model identifier
`model_router_error`	503	Intelligent routing failed	Retry or use specific model
`provider_failure`	503	Individual provider error	Check provider status

Error Response Structure

All Adaptive errors follow this consistent JSON structure:

{
  "error": {
    "type": "error_type",
    "message": "Human-readable error message",
    "details": {
      // Error-specific details (varies by error type)
    }
  }
}

Common Fields:

type: Error category (see table above)
message: Human-readable description
details: Error-specific information (optional)

Authentication Errors (401)

Invalid API Key

Error Response:

{
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key"
  }
}

Causes:

Incorrect API key
Missing or malformed authorization header
Expired or revoked key

Solutions:

Verify your API key from the Adaptive dashboard

Check header format:

 // ✅ Correct
 headers: { "Authorization": "Bearer apk_123456" }

 // ❌ Wrong
 headers: { "X-API-Key": "your-key" }  // Wrong header name

Validation Errors (400)

Invalid Request Format

Error Response:

{
  "error": {
    "type": "invalid_request_error",
    "message": "Invalid request format"
  }
}

Common Causes:

Missing required fields
Invalid JSON structure
Unsupported parameter values
Model identifier format issues

Examples:

// Missing required field
{
  "error": {
    "type": "invalid_request_error",
    "message": "messages: Field required"
  }
}

// Invalid model format
{
  "error": {
    "type": "invalid_request_error",
    "message": "model: Invalid model identifier"
  }
}

Fallback Errors (503) ⭐ Unique to Adaptive

Adaptive’s Signature Feature: When intelligent routing exhausts all provider options, you get detailed failure insights from every provider attempt.

Overview

Fallback errors occur when Adaptive’s intelligent routing tries all available providers but none succeed. This provides unprecedented visibility into multi-provider failures. Key Benefits:

See exactly which providers failed and why
Understand if it’s a widespread outage or isolated issues
Make informed retry decisions based on failure patterns

Sequential vs Race Mode

Adaptive supports two fallback modes:

Sequential: Try providers one by one until success
Race: Try all providers simultaneously, return first success

Error Response Structure

{
  "error": {
    "type": "fallback_failed",
    "message": "all 3 providers failed (sequential mode)",
    "details": {
      "mode": "sequential",
      "attempts": 3,
      "failures": [
        {
          "provider": "openai",
          "model": "gpt-4",
          "error": "Rate limit exceeded",
          "duration_ms": 1250
        },
        {
          "provider": "anthropic",
          "model": "claude-3-opus",
          "error": "Service temporarily unavailable",
          "duration_ms": 2100
        },
        {
          "provider": "google",
          "model": "gemini-pro",
          "error": "Quota exceeded",
          "duration_ms": 980
        }
      ]
    }
  }
}

Provider Failure Details

Each failure in the failures array contains:

provider: Provider name ("openai", "anthropic", "google")
model: Specific model that was attempted
error: Provider’s error message
duration_ms: How long the request took (performance insight)

Recovery Strategies

🔄 All Rate Limits (429)

Pattern: All failures show rate limitingStrategy:

Implement exponential backoff: 1s → 2s → 4s → 8s
Consider request queuing
Check your rate limit tier

Code Example:

async function retryWithBackoff(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.response?.data?.error?.type !== 'fallback_failed') {
        throw error;
      }

      const isAllRateLimits = error.response.data.error.details.failures
        .every(f => f.error.includes('rate limit'));

      if (!isAllRateLimits || i === maxRetries - 1) {
        throw error;
      }

      await new Promise(resolve => setTimeout(resolve, 2 ** i * 1000));
    }
  }
}

⚡ Mixed Provider Errors

Pattern: Different errors from different providersStrategy:

Retry immediately (may be transient)
Check status page for outages
Consider degraded mode operation

Code Example:

catch (error) {
  const failures = error.response?.data?.error?.details?.failures;
  if (failures) {
    const hasOutage = failures.some(f => f.error.includes('unavailable'));
    if (hasOutage) {
      // Degraded mode: use cached responses or simplified answers
      return getCachedResponse(query);
    }
  }
  throw error;
}

⏱️ High Latency Failures

Pattern: duration_ms > 5000 for multiple providersStrategy:

Check network connectivity
Consider timeout adjustments
Use race mode for faster failures

Code Example:

// For high-latency scenarios, use race mode
const response = await fetch('https://api.llmadaptive.uk/v1/chat/completions', {
  method: 'POST',
   headers: {
     'Content-Type': 'application/json',
     'Authorization': 'Bearer apk_123456',
     'X-Adaptive-Mode': 'race'  // Faster failure detection
   },
  body: JSON.stringify({ /* request */ })
});

Model Registry Errors (404/503)

Model Not Found

Error Response:

{
  "error": {
    "type": "model_registry_error",
    "message": "Model 'invalid-model' not found"
  }
}

Causes:

Invalid model identifier
Model not available in your region
Model temporarily disabled

Solutions:

Check available models: GET /v1/models
Use empty string "" for intelligent routing
Verify model name spelling

Model Router Errors (503)

Routing Failure

Error Response:

{
  "error": {
    "type": "model_router_error",
    "message": "Unable to route request to appropriate model"
  }
}

Causes:

All models filtered out by routing logic
Complex prompt that doesn’t match any model
Routing service temporarily unavailable

Solutions:

Specify a model explicitly instead of using ""
Simplify your prompt if using intelligent routing
Retry with backoff

Provider-Specific Errors

Pass-Through Errors

When a specific provider returns an error, Adaptive passes it through with additional context:

{
  "error": {
    "type": "provider_failure",
    "message": "OpenAI API error: Rate limit exceeded",
    "details": {
      "provider": "openai",
      "model": "gpt-4",
      "original_error": {
        "type": "rate_limit_exceeded",
        "message": "Rate limit exceeded"
      }
    }
  }
}

Common Provider Errors:

OpenAI: Rate limits, content policy violations, token limits
Anthropic: Rate limits, context length exceeded
Google: Quota exceeded, safety filters

See Provider Documentation:

Troubleshooting Guide

By HTTP Status Code

401 Unauthorized

Always check:

API key is correct and active
Header format matches documentation
No extra spaces or characters in key

Quick Test:

curl -H "Authorization: Bearer apk_123456" \
     https://api.llmadaptive.uk/v1/models

400 Bad Request

Check:

JSON is valid and properly formatted
Required fields are present
Parameter values are within limits
Model identifier is correct

404 Not Found

Check:

Endpoint URL is correct
Model exists (GET /v1/models)
Method is correct (POST vs GET)

503 Service Unavailable

Could be:

FallbackError (all providers failed)
Model routing failure
Service maintenance

Check details field for specific cause

By Symptom

Requests work sometimes but fail others

Likely causes:

Rate limiting (check usage dashboard)
Provider-specific outages
Network issues

Solution: Implement retry logic

All requests fail immediately

Likely causes:

Authentication issues
Invalid request format
Service outage

Solution: Check error details and dashboard

Requests take very long then fail

Likely causes:

Network connectivity issues
Provider timeouts
High server load

Solution: Check duration_ms in error details

Best Practices

Error Handling Patterns

Always catch errors - Never let them crash your application
Log request IDs - Essential for support investigations
Implement retries - With exponential backoff for transient errors
Monitor error rates - Set up alerts for increased failure rates

Production Checklist

Implement comprehensive error handling
Add request ID logging
Set up retry logic with backoff
Monitor error rates and alert thresholds
Test failure scenarios in development
Document error handling in your codebase

Next Steps

For production-ready error handling patterns, see the Error Handling Best Practices guide.

Getting Started

Key Features

Framework Integrations

Developer Tools

Examples

API Reference

Support

Overview

Quick Reference

Error Response Structure

Authentication Errors (401)

Invalid API Key

Validation Errors (400)

Invalid Request Format

Fallback Errors (503) ⭐ Unique to Adaptive

Overview

Sequential vs Race Mode

Error Response Structure

Provider Failure Details

Recovery Strategies

Model Registry Errors (404/503)

Model Not Found

Model Router Errors (503)

Routing Failure

Provider-Specific Errors

Pass-Through Errors

Troubleshooting Guide

By HTTP Status Code

By Symptom

Best Practices

Error Handling Patterns

Production Checklist

Next Steps

Getting Started

Key Features

Framework Integrations

Developer Tools

Examples

API Reference

Support

​Overview

​Quick Reference

​Error Response Structure

​Authentication Errors (401)

​Invalid API Key

​Validation Errors (400)

​Invalid Request Format

​Fallback Errors (503) ⭐ Unique to Adaptive

​Overview

​Sequential vs Race Mode

​Error Response Structure

​Provider Failure Details

​Recovery Strategies

​Model Registry Errors (404/503)

​Model Not Found

​Model Router Errors (503)

​Routing Failure

​Provider-Specific Errors

​Pass-Through Errors

​Troubleshooting Guide

​By HTTP Status Code

​By Symptom

​Best Practices

​Error Handling Patterns

​Production Checklist

​Next Steps

Overview

Quick Reference

Error Response Structure

Authentication Errors (401)

Invalid API Key

Validation Errors (400)

Invalid Request Format

Fallback Errors (503) ⭐ Unique to Adaptive

Overview

Sequential vs Race Mode

Error Response Structure

Provider Failure Details

Recovery Strategies

Model Registry Errors (404/503)

Model Not Found

Model Router Errors (503)

Routing Failure

Provider-Specific Errors

Pass-Through Errors

Troubleshooting Guide

By HTTP Status Code

By Symptom

Best Practices

Error Handling Patterns

Production Checklist

Next Steps