Troubleshooting

Common Issues

Authentication Problems

401 Unauthorized Error

Problem: Getting authentication errors when making API calls.Solutions:

Check your API key:

# Verify your API key is set correctly
echo $ADAPTIVE_API_KEY

Ensure correct format:

// Correct - no 'Bearer' prefix needed
const openai = new OpenAI({
  apiKey: 'your-adaptive-api-key',
  baseURL: 'https://api.llmadaptive.uk/v1'
});

Verify API key validity:
- Check if your API key has expired
- Ensure you’re using the correct key for your environment
- Try regenerating your API key in the dashboard

Test with curl:

curl -H "X-Stainless-API-Key: your-adaptive-api-key" \
     -H "Content-Type: application/json" \
     https://api.llmadaptive.uk/v1/chat/completions \
     -d '{"model":"","messages":[{"role":"user","content":"test"}]}'

API Key Not Found

Problem: Environment variable not being loaded.Solutions:

Check environment variable:

# In terminal
export ADAPTIVE_API_KEY=your-key-here

# Or in .env file
echo "ADAPTIVE_API_KEY=your-key-here" >> .env

Load environment variables:

// Node.js
require('dotenv').config();

// Or using ES modules
import 'dotenv/config';

Python environment:

import os
from dotenv import load_dotenv

load_dotenv()
api_key = os.getenv("ADAPTIVE_API_KEY")

Configuration Issues

Wrong Base URL

Problem: Using incorrect base URL causing connection failures.Correct base URL:

https://api.llmadaptive.uk/v1

Common mistakes:

// ❌ Wrong
baseURL: 'https://api.openai.com/v1'
baseURL: 'https://adaptive.ai/api/v1'
baseURL: 'https://www.llmadaptive.uk/v1'

// ✅ Correct
baseURL: 'https://api.llmadaptive.uk/v1'

Model Parameter Issues

Problem: Intelligent routing not working or model errors.Solutions:

Use empty string for intelligent routing:

// ✅ Correct - enables intelligent routing
model: ""

// ❌ Wrong - tries to use specific model
model: ""
model: ""
model: ""

TypeScript type issues:

// Option 1: Type assertion
model: "" as any

// Option 2: Disable strict checking for this parameter
// @ts-ignore
model: ""

SSL/TLS Certificate Errors

Problem: Certificate validation errors in some environments.Solutions:

Update certificates:

# Ubuntu/Debian
sudo apt-get update && sudo apt-get install ca-certificates

# macOS
brew install ca-certificates

Node.js certificate issues:

// Temporary workaround (not recommended for production)
process.env["NODE_TLS_REJECT_UNAUTHORIZED"] = 0;

// Better solution: update Node.js or certificates

Python certificate issues:

import ssl
import certifi

# Ensure certificates are up to date
ssl.create_default_context(cafile=certifi.where())

Request/Response Issues

Empty or No Response

Problem: Getting empty responses or no content.Diagnostic steps:

Check request format:

const completion = await openai.chat.completions.create({
  model: "",
  messages: [
    { role: "user", content: "Hello" } // Ensure content is not empty
  ]
});

Verify response handling:

console.log("Full response:", completion);
console.log("Content:", completion.choices[0]?.message?.content);
console.log("Provider:", completion.provider);

Check for API errors:

try {
  const completion = await openai.chat.completions.create({...});
} catch (error) {
  console.log("Error details:", error);
  console.log("Status:", error.status);
  console.log("Message:", error.message);
}

Streaming Not Working

Problem: Streaming responses not appearing or failing.Solutions:

Check streaming syntax:

// ✅ Correct streaming setup
const stream = await openai.chat.completions.create({
  model: "",
  messages: [...],
  stream: true
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content || '');
}

Browser streaming with fetch:

const response = await fetch('/api/stream-chat', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ message })
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  
  const chunk = decoder.decode(value);
  // Process chunk...
}

Server-sent events setup:

// Server
res.writeHead(200, {
  'Content-Type': 'text/event-stream',
  'Cache-Control': 'no-cache',
  'Connection': 'keep-alive'
});

Rate Limiting Errors

Problem: Getting 429 errors (rate limit exceeded).Solutions:

Implement exponential backoff:

async function retryWithBackoff(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.status === 429 && i < maxRetries - 1) {
        const delay = Math.pow(2, i) * 1000; // 1s, 2s, 4s
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }
      throw error;
    }
  }
}

Check your rate limits:
- Free tier: 100 requests/minute, 10,000 tokens/minute
- Pro tier: 1,000 requests/minute, 100,000 tokens/minute
- Enterprise: Custom limits

Implement request queuing:

class RequestQueue {
  constructor(maxPerMinute = 100) {
    this.queue = [];
    this.maxPerMinute = maxPerMinute;
    this.requestTimes = [];
  }
  
  async enqueue(requestFn) {
    return new Promise((resolve, reject) => {
      this.queue.push({ requestFn, resolve, reject });
      this.processQueue();
    });
  }
  
  async processQueue() {
    if (this.queue.length === 0) return;
    
    const now = Date.now();
    this.requestTimes = this.requestTimes.filter(time => now - time < 60000);
    
    if (this.requestTimes.length < this.maxPerMinute) {
      const { requestFn, resolve, reject } = this.queue.shift();
      this.requestTimes.push(now);
      
      try {
        const result = await requestFn();
        resolve(result);
      } catch (error) {
        reject(error);
      }
      
      // Process next request
      setTimeout(() => this.processQueue(), 100);
    } else {
      // Wait and try again
      setTimeout(() => this.processQueue(), 1000);
    }
  }
}

Integration-Specific Issues

LangChain Integration Problems

Problem: LangChain not working with Adaptive.Solutions:

Correct LangChain setup:

# Python
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    api_key=os.getenv("ADAPTIVE_API_KEY"),
    base_url="https://api.llmadaptive.uk/v1",
    model=""  # Important: empty string
)

// JavaScript
import { ChatOpenAI } from "@langchain/openai";

const llm = new ChatOpenAI({
  apiKey: process.env.ADAPTIVE_API_KEY,
  configuration: {
    baseURL: "https://api.llmadaptive.uk/v1"
  },
  model: ""
});

Handle LangChain-specific errors:

from openai import APIError

try:
    response = llm.invoke("Hello")
except APIError as e:
    print(f"API Error: {e}")
except Exception as e:
    print(f"Other error: {e}")

Vercel AI SDK Issues

Problem: Vercel AI SDK not connecting properly.Solutions:

Using OpenAI provider method:

import { openai } from '@ai-sdk/openai';

const adaptiveOpenAI = openai({
  apiKey: process.env.ADAPTIVE_API_KEY,
  baseURL: 'https://api.llmadaptive.uk/v1',
});

const { text } = await generateText({
  model: adaptiveOpenAI(''), // Empty string for routing
  prompt: 'Hello'
});

TypeScript issues:

// If getting type errors
const model = adaptiveOpenAI('' as any);

Environment variables in Next.js:

// next.config.js
module.exports = {
  env: {
    ADAPTIVE_API_KEY: process.env.ADAPTIVE_API_KEY,
  },
};

Performance Issues

Slow Response Times

Problem: Responses taking longer than expected.Diagnostic steps:

Check routing decisions:

const completion = await openai.chat.completions.create({
  model: "",
  messages: [...]
});

console.log("Selected provider:", completion.provider);
console.log("Selected model:", completion.model);

Optimize with cost_bias:

// Prefer faster, cheaper models
const completion = await openai.chat.completions.create({
  model: "",
  messages: [...],
  cost_bias: 0.2 // 0 = cheapest/fastest, 1 = best quality
});

Use provider constraints for speed:

// Route only to fast providers
const completion = await openai.chat.completions.create({
  model: "",
  messages: [...],
  provider_constraint: ["groq", "gemini"] // Fast providers
});

High Latency

Problem: Network latency issues.Solutions:

Check your network:

# Test connectivity
ping llmadaptive.uk

# Test TLS handshake
curl -w "@curl-format.txt" -o /dev/null https://api.llmadaptive.uk/v1/

Implement timeout handling:

const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), 30000); // 30s timeout

try {
  const completion = await openai.chat.completions.create({
    model: "",
    messages: [...]
  }, {
    signal: controller.signal
  });
} catch (error) {
  if (error.name === 'AbortError') {
    console.log('Request timed out');
  }
} finally {
  clearTimeout(timeoutId);
}

Use connection pooling:

import https from 'https';

const agent = new https.Agent({
  keepAlive: true,
  maxSockets: 10
});

const openai = new OpenAI({
  apiKey: process.env.ADAPTIVE_API_KEY,
  baseURL: 'https://api.llmadaptive.uk/v1',
  httpAgent: agent
});

Development Environment Issues

CORS Issues in Browser

Problem: Cross-origin resource sharing errors.Solutions:

Never call API directly from browser:

// ❌ Wrong - exposes API key
// const completion = await openai.chat.completions.create({...});

// ✅ Correct - use your backend
const response = await fetch('/api/chat', {
  method: 'POST',
  body: JSON.stringify({ message })
});

Set up proxy in development:

// Next.js API route
// pages/api/chat.js
export default async function handler(req, res) {
  const completion = await openai.chat.completions.create({
    model: "",
    messages: req.body.messages
  });
  
  res.json({ response: completion.choices[0].message.content });
}

Configure CORS for your backend:

// Express.js
app.use(cors({
  origin: ['http://localhost:3000', 'https://yourdomain.com'],
  credentials: true
}));

TypeScript Compilation Errors

Problem: TypeScript errors with Adaptive integration.Solutions:

Install correct types:

npm install --save-dev @types/node
npm install openai  # Latest version includes types

Type assertion for model parameter:

const completion = await openai.chat.completions.create({
  model: "" as any, // Type assertion
  messages: [...]
});

Create custom types if needed:

interface AdaptiveCompletion extends ChatCompletion {
  provider: string;
}

Module Import Errors

Problem: ES modules vs CommonJS issues.Solutions:

Use correct imports:

// ES modules
import OpenAI from 'openai';

// CommonJS
const OpenAI = require('openai');

Package.json configuration:

{
  "type": "module",
  "dependencies": {
    "openai": "^4.0.0"
  }
}

Node.js version compatibility:

# Check Node.js version
node --version

# Adaptive requires Node.js 18+
# Update if necessary

Getting Help

Debug Information to Collect

When reporting issues, please include:

Environment Details

# System info
node --version
npm --version

# Package versions
npm list openai
npm list @langchain/openai

Request Details

// Sanitized request (remove API key)
{
  "model": "",
  "messages": [...],
  "provider_constraint": [...],
  "cost_bias": 0.5
}

Error Information

console.log("Error status:", error.status);
console.log("Error message:", error.message);
console.log("Error stack:", error.stack);

Network Diagnostics

# Test connectivity
curl -I https://api.llmadaptive.uk/v1/

# DNS resolution
nslookup llmadaptive.uk

Support Channels

Documentation

Check our comprehensive guides and API reference for solutions

GitHub Issues

Report bugs and request features on our GitHub repository

Discord Community

Get help from the community and Adaptive team members

Email Support

Contact support@adaptive.com for priority assistance

Best Practices for Debugging

Start with Simple Requests

Test basic functionality first

const simple = await openai.chat.completions.create({
  model: "",
  messages: [{ role: "user", content: "Hello" }]
});

Enable Verbose Logging

Add detailed logging to understand what’s happening

console.log("Request:", JSON.stringify(requestData, null, 2));
console.log("Response:", JSON.stringify(response, null, 2));

Test with curl

Verify API access outside your application

curl -X POST https://api.llmadaptive.uk/v1/chat/completions \
  -H "X-Stainless-API-Key: $ADAPTIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"","messages":[{"role":"user","content":"test"}]}'

Isolate the Problem

Systematically narrow down the issue:

Test different messages
Try different parameters
Test in different environments
Compare with working examples

Complete Error Handling Example

Here’s a production-ready error handling implementation:

class AdaptiveClient {
  constructor(apiKey) {
    this.openai = new OpenAI({
      apiKey: apiKey,
      baseURL: 'https://api.llmadaptive.uk/v1'
    });
  }
  
  async createCompletion(params, retries = 3) {
    for (let attempt = 1; attempt <= retries; attempt++) {
      try {
        const completion = await this.openai.chat.completions.create({
          model: "",
          ...params
        });
        
        // Log success metrics
        console.log(`✅ Success: ${completion.provider} | ${completion.usage.total_tokens} tokens`);
        return completion;
        
      } catch (error) {
        // Handle specific errors
        if (error.status === 401) {
          throw new Error('Invalid API key - check your credentials');
        }
        
        if (error.status === 429) {
          const delay = Math.min(1000 * Math.pow(2, attempt), 10000);
          console.log(`⚠️  Rate limited, retrying in ${delay}ms (attempt ${attempt}/${retries})`);
          
          if (attempt < retries) {
            await new Promise(resolve => setTimeout(resolve, delay));
            continue;
          }
          throw new Error('Rate limit exceeded - reduce request frequency');
        }
        
        if (error.status === 400) {
          throw new Error(`Invalid request: ${error.message}`);
        }
        
        if (error.status >= 500) {
          const delay = 1000 * attempt;
          console.log(`🔄 Server error, retrying in ${delay}ms (attempt ${attempt}/${retries})`);
          
          if (attempt < retries) {
            await new Promise(resolve => setTimeout(resolve, delay));
            continue;
          }
          throw new Error('Server error - try again later');
        }
        
        // Unexpected error
        throw new Error(`Unexpected error: ${error.message}`);
      }
    }
  }
}

// Usage example
const client = new AdaptiveClient(process.env.ADAPTIVE_API_KEY);

try {
  const response = await client.createCompletion({
    messages: [{ role: "user", content: "Hello!" }],
    model_router: {
      cost_bias: 0.3,
      models: ["openai:gpt-5-mini", "anthropic:claude-sonnet-4-5"]
    }
  });
  
  console.log("Response:", response.choices[0].message.content);
} catch (error) {
  console.error("Failed to get completion:", error.message);
}

FAQ

Why am I not getting responses from certain providers?

Check your model_router.models configuration. Ensure the providers you want are included and your cost_bias setting allows for the provider selection you expect.

How do I know which provider was selected?

Check the provider field in the response:

console.log("Selected provider:", completion.provider);
console.log("Model used:", completion.model);

Can I force a specific model?

Use the model_router.models array with specific model names:

model_router: {
  models: [
    "openai:gpt-5-mini"
  ]
}

Why are my costs higher than expected?

Check your cost_bias setting. A higher value (closer to 1) prioritizes quality over cost. Set it to 0.0-0.3 for maximum cost savings.

How do I disable semantic caching?

Set semantic cache to disabled in your request:

semantic_cache: {
  enabled: false
}

Getting Started

Framework Integrations

Developer Tools

Key Features

API Reference

Support

Common Issues

Authentication Problems

Configuration Issues

Request/Response Issues

Integration-Specific Issues

Performance Issues

Development Environment Issues

Getting Help

Debug Information to Collect

Support Channels

Documentation

GitHub Issues

Discord Community

Email Support

Best Practices for Debugging

Complete Error Handling Example

FAQ

Getting Started

Framework Integrations

Developer Tools

Key Features

API Reference

Support

​Common Issues

​Authentication Problems

​Configuration Issues

​Request/Response Issues

​Integration-Specific Issues

​Performance Issues

​Development Environment Issues

​Getting Help

​Debug Information to Collect

​Support Channels

Documentation

GitHub Issues

Discord Community

Email Support

​Best Practices for Debugging

​Complete Error Handling Example

​FAQ

Common Issues

Authentication Problems

Configuration Issues

Request/Response Issues

Integration-Specific Issues

Performance Issues

Development Environment Issues

Getting Help

Debug Information to Collect

Support Channels

Best Practices for Debugging

Complete Error Handling Example

FAQ