Error Handling

Overview

The Concentrate AI API uses standard HTTP status codes to indicate success or failure. All error responses include a JSON body with details about what went wrong.

Error Response Format

All errors follow this structure:

{
  "error": "Error type or message",
  "message": "Detailed explanation (optional)",
  "model": "provider/model (for provider errors only)"
}

Status Codes

Status Code	Error Type	Description
`200`	Success	Request completed successfully
`400`	Bad Request	Invalid request parameters
`401`	Unauthorized	Missing or invalid API key
`402`	Payment Required	Insufficient credits
`424`	Failed Dependency	Provider unavailable
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Server Error	Server-side error
`503`	Service Unavailable	Service temporarily unavailable
`504`	Gateway Timeout	Upstream provider did not respond in time

Error Types

400 Bad Request

Invalid or malformed request parameters.

Invalid Model Name

{
  "error": "Bad Request",
  "message": "Invalid model name: 'invalid-model-xyz'"
}

Causes:

Model doesn’t exist
Typo in model name
Unsupported model

Solution:

Check supported models list
Verify spelling and format
Use provider prefix format: provider/model

Missing Required Fields

{
  "error": "Bad Request",
  "message": "Missing required field: 'input'"
}

Causes:

Required parameter not provided
Empty or null value

Solution:

Include all required fields: model and input
Ensure values are not null or empty

Invalid Parameter Type

{
  "error": "Bad Request",
  "message": "Invalid type for 'temperature': expected number, got string"
}

Causes:

Wrong data type for parameter
Invalid enum value

Solution:

Check parameter types in API reference
Use correct data types (string, number, boolean, etc.)

Invalid Parameter Value

{
  "error": "Bad Request",
  "message": "temperature must be between 0 and 2, got 3.5"
}

Causes:

Value outside allowed range
Negative value for positive-only fields

Solution:

Review parameter constraints
temperature: 0.0 - 2.0
top_p: 0.0 - 1.0
max_output_tokens: > 0

401 Unauthorized

Authentication failed or API key is invalid.

{
  "error": "Unauthorized",
  "message": "Invalid API key"
}

Causes:

API key is missing
API key is invalid or revoked
Wrong header format

Solutions:

# Correct
Authorization: Bearer sk-cn-v1-abc123xyz789

# Incorrect
Authorization: sk-cn-v1-abc123xyz789  # Missing "Bearer"
Authorization: Bearer: sk-cn-v1-abc123xyz789  # Extra colon

import requests

# Test authentication
response = requests.post(
    "https://api.concentrate.ai/v1/responses/health",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)

if response.status_code == 401:
    print("API key is invalid")
else:
    print("API key is valid")

Get a new API key from the Concentrate AI dashboard if yours is invalid.

402 Payment Required

Insufficient credits to complete the request.

{
  "error": "Insufficient funds",
  "message": "Your account has insufficient credits. Please add credits to continue."
}

Causes:

Account credit balance too low
Request would exceed credit limit
Free tier exhausted

Solutions:

Check your balance:
- Visit dashboard
- View credit usage and remaining balance
Add credits:
- Purchase additional credits
- Upgrade your plan
Optimize requests:
- Reduce max_output_tokens
- Use cost-optimized models
- Enable auto routing with routing: { strategy: "min", metric: "cost" }

import requests

def make_request_with_budget(input_text):
    # Try with primary model
    response = requests.post(
        "https://api.concentrate.ai/v1/responses",
        headers={"Authorization": "Bearer YOUR_API_KEY"},
        json={
            "model": "gpt-5.2",
            "input": input_text,
            "max_output_tokens": 500
        }
    )

    if response.status_code == 402:
        # Try a cheaper model
        response = requests.post(
            "https://api.concentrate.ai/v1/responses",
            headers={"Authorization": "Bearer YOUR_API_KEY"},
            json={
                "model": "auto",
                "input": input_text,
                "routing": {
                    "provider": {"sort": "cost"}
                },
                "max_output_tokens": 300
            }
        )

    return response.json()

async function makeRequest(input) {
  try {
    const response = await fetch("https://api.concentrate.ai/v1/responses", {
      method: "POST",
      headers: {
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
      },
      body: JSON.stringify({
        model: "gpt-5.2",
        input
      })
    });

    if (response.status === 402) {
      // Notify user to add credits
      showCreditWarning();
      return null;
    }

    return await response.json();
  } catch (error) {
    handleError(error);
  }
}

424 Failed Dependency

The requested provider is unavailable.

{
  "error": "Model 'openai/gpt-5.2' Errored",
  "message": "Request to openai/gpt-5.2 failed because provider was unavailable",
  "model": "openai/gpt-5.2"
}

Causes:

Provider experiencing outage
Model temporarily unavailable
Regional restrictions

Solutions:

Retry with exponential backoff
Specify alternative provider

import time
import requests

def request_with_retry(payload, max_retries=3):
    for attempt in range(max_retries):
        response = requests.post(
            "https://api.concentrate.ai/v1/responses",
            headers={"Authorization": "Bearer YOUR_API_KEY"},
            json=payload
        )

        if response.status_code == 424:
            if attempt < max_retries - 1:
                # Exponential backoff: 1s, 2s, 4s
                wait_time = 2 ** attempt
                print(f"Provider error, retrying in {wait_time}s...")
                time.sleep(wait_time)
                continue

        return response.json()

    raise Exception("All retry attempts failed")

async function requestWithAlternative(input) {
  // Try specific provider
  let response = await fetch("https://api.concentrate.ai/v1/responses", {
    method: "POST",
    headers: {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      model: "openai/gpt-5.2",
      input
    })
  });

  // If provider fails, try a different provider/model
  if (response.status === 424) {
    response = await fetch("https://api.concentrate.ai/v1/responses", {
      method: "POST",
      headers: {
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
      },
      body: JSON.stringify({
        model: "anthropic/claude-sonnet-4-5",
        input
      })
    });
  }

  return await response.json();
}

Implement client-side retry logic or specify an alternative provider/model to handle provider unavailability.

429 Too Many Requests

Rate limit exceeded.

{
  "error": "Rate limit exceeded",
  "message": "Too many requests. Please retry after 60 seconds.",
  "retry_after": 60
}

Causes:

Exceeded requests per minute limit
Too many tokens per minute
Burst limit exceeded

Solutions:

Implement rate limiting in your code
Use exponential backoff
Batch requests when possible
Upgrade plan for higher limits

import time
import requests

def make_request_with_rate_limit(payload):
    while True:
        response = requests.post(
            "https://api.concentrate.ai/v1/responses",
            headers={"Authorization": "Bearer YOUR_API_KEY"},
            json=payload
        )

        if response.status_code == 429:
            # Get retry-after header
            retry_after = int(response.headers.get('Retry-After', 60))
            print(f"Rate limited. Waiting {retry_after}s...")
            time.sleep(retry_after)
            continue

        return response.json()

class RateLimiter {
  constructor(tokensPerMinute) {
    this.tokens = tokensPerMinute;
    this.maxTokens = tokensPerMinute;
    this.lastRefill = Date.now();
  }

  async waitForToken() {
    // Refill tokens
    const now = Date.now();
    const timePassed = (now - this.lastRefill) / 1000;
    this.tokens = Math.min(
      this.maxTokens,
      this.tokens + (timePassed * this.maxTokens / 60)
    );
    this.lastRefill = now;

    // Wait if no tokens available
    if (this.tokens < 1) {
      const waitTime = ((1 - this.tokens) / (this.maxTokens / 60)) * 1000;
      await new Promise(resolve => setTimeout(resolve, waitTime));
      this.tokens = 1;
    }

    this.tokens -= 1;
  }

  async makeRequest(payload) {
    await this.waitForToken();

    return fetch("https://api.concentrate.ai/v1/responses", {
      method: "POST",
      headers: {
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
      },
      body: JSON.stringify(payload)
    });
  }
}

// Usage
const limiter = new RateLimiter(60); // 60 requests per minute
const response = await limiter.makeRequest({
  model: "gpt-5.2",
  input: "Hello"
});

500 Internal Server Error

Server-side error. These are rare and usually temporary.

{
  "error": "Internal server error",
  "message": "An unexpected error occurred. Please try again."
}

Causes:

Temporary server issue
Unexpected error condition
Any provider internal error (e.g., an outage at an upstream provider)

Solutions:

Retry the request after a short delay
If persists, contact support

503 Service Unavailable

The service is temporarily unable to handle the request. Unlike a 500, this signals a capacity or availability condition rather than an unexpected failure, so the same request is likely to succeed shortly.

{
  "error": "Service Unavailable",
  "message": "Service temporarily unavailable, please try again"
}

Causes:

The API is shedding load during a traffic burst
A dependency required to serve the request is temporarily unavailable

Solutions:

Retry with exponential backoff and jitter
If a Retry-After header is present, wait at least that long before retrying
If it persists across several minutes, check status.concentrate.ai

504 Gateway Timeout

The upstream provider did not respond within the allowed time window. The request reached the provider, so it may have been partially processed.

{
  "error": "Gateway Timeout",
  "message": "Upstream provider did not respond in time"
}

Causes:

The upstream provider is slow or degraded
A very large prompt or max_output_tokens value pushed the request past the timeout

Solutions:

Retry the request, optionally with a smaller prompt or lower max_output_tokens
Add model fallbacks so routing can move to another provider
Use streaming for long generations, which begins delivering output before the full response is complete

503 and 504 are both safe to retry. Because a 504 may leave a partially processed request upstream, avoid blindly retrying non-idempotent work without checking whether the first attempt was billed.

Best Practices

Implement comprehensive error handling

import requests
from typing import Optional

def make_safe_request(payload: dict) -> Optional[dict]:
    try:
        response = requests.post(
            "https://api.concentrate.ai/v1/responses",
            headers={"Authorization": "Bearer YOUR_API_KEY"},
            json=payload,
            timeout=30
        )

        # Handle different status codes
        if response.status_code == 200:
            return response.json()
        elif response.status_code == 400:
            print(f"Bad request: {response.json()['message']}")
        elif response.status_code == 401:
            print("Authentication failed - check API key")
        elif response.status_code == 402:
            print("Insufficient credits - please add funds")
        elif response.status_code == 424:
            print(f"Provider error: {response.json()['message']}")
            # Implement retry or try alternative provider
        elif response.status_code == 429:
            retry_after = int(response.headers.get('Retry-After', 60))
            print(f"Rate limited - retry after {retry_after}s")
        elif response.status_code == 500:
            print("Server error - will retry")
        elif response.status_code == 503:
            print("Service unavailable - will retry with backoff")
        elif response.status_code == 504:
            print("Upstream provider timed out - will retry")

        return None

    except requests.exceptions.Timeout:
        print("Request timed out")
    except requests.exceptions.ConnectionError:
        print("Connection failed")
    except Exception as e:
        print(f"Unexpected error: {str(e)}")

    return None

Log errors for debugging

async function makeRequestWithLogging(payload) {
  const startTime = Date.now();

  try {
    const response = await fetch("https://api.concentrate.ai/v1/responses", {
      method: "POST",
      headers: {
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
      },
      body: JSON.stringify(payload)
    });

    const data = await response.json();
    const duration = Date.now() - startTime;

    // Log all requests
    console.log({
      timestamp: new Date().toISOString(),
      status: response.status,
      model: payload.model,
      duration,
      success: response.ok
    });

    if (!response.ok) {
      // Log error details
      console.error({
        error: data.error,
        message: data.message,
        payload
      });
    }

    return data;
  } catch (error) {
    console.error({
      timestamp: new Date().toISOString(),
      error: error.message,
      payload
    });
    throw error;
  }
}

Use circuit breaker pattern

from datetime import datetime, timedelta

class CircuitBreaker:
    def __init__(self, failure_threshold=5, timeout=60):
        self.failure_threshold = failure_threshold
        self.timeout = timeout
        self.failures = 0
        self.last_failure_time = None
        self.state = "closed"  # closed, open, half-open

    def call(self, func, *args, **kwargs):
        if self.state == "open":
            if datetime.now() - self.last_failure_time > timedelta(seconds=self.timeout):
                self.state = "half-open"
            else:
                raise Exception("Circuit breaker is open")

        try:
            result = func(*args, **kwargs)
            self.on_success()
            return result
        except Exception as e:
            self.on_failure()
            raise

    def on_success(self):
        self.failures = 0
        self.state = "closed"

    def on_failure(self):
        self.failures += 1
        self.last_failure_time = datetime.now()
        if self.failures >= self.failure_threshold:
            self.state = "open"

# Usage
breaker = CircuitBreaker()

try:
    response = breaker.call(make_api_request, payload)
except Exception as e:
    print(f"Request failed: {e}")

Validate before sending

interface RequestPayload {
  model: string;
  input: string | Message[];
  temperature?: number;
  max_output_tokens?: number;
}

function validatePayload(payload: RequestPayload): string[] {
  const errors: string[] = [];

  if (!payload.model) {
    errors.push("model is required");
  }

  if (!payload.input) {
    errors.push("input is required");
  }

  if (payload.temperature !== undefined) {
    if (payload.temperature < 0 || payload.temperature > 2) {
      errors.push("temperature must be between 0 and 2");
    }
  }

  if (payload.max_output_tokens !== undefined) {
    if (payload.max_output_tokens < 1) {
      errors.push("max_output_tokens must be positive");
    }
  }

  return errors;
}

// Usage
const payload = { model: "gpt-5.2", input: "Hello" };
const errors = validatePayload(payload);

if (errors.length > 0) {
  console.error("Validation errors:", errors);
} else {
  // Make request
}

Error Monitoring

Track and analyze errors in production:

from collections import Counter
from datetime import datetime

class ErrorTracker:
    def __init__(self):
        self.errors = []

    def log_error(self, status_code, error, message):
        self.errors.append({
            "timestamp": datetime.now(),
            "status_code": status_code,
            "error": error,
            "message": message
        })

    def get_error_summary(self):
        status_counts = Counter(e["status_code"] for e in self.errors)
        error_counts = Counter(e["error"] for e in self.errors)

        return {
            "total_errors": len(self.errors),
            "by_status": dict(status_counts),
            "by_type": dict(error_counts)
        }

tracker = ErrorTracker()

# Log errors
if response.status_code != 200:
    data = response.json()
    tracker.log_error(
        response.status_code,
        data.get("error"),
        data.get("message")
    )

# Get summary
print(tracker.get_error_summary())

class ErrorAnalytics {
  constructor() {
    this.errors = [];
  }

  logError(statusCode, error, message) {
    this.errors.push({
      timestamp: new Date(),
      statusCode,
      error,
      message
    });
  }

  getErrorRate(windowMinutes = 60) {
    const cutoff = new Date(Date.now() - windowMinutes * 60 * 1000);
    const recentErrors = this.errors.filter(e => e.timestamp > cutoff);
    return recentErrors.length;
  }

  getMostCommonError() {
    const counts = {};
    for (const error of this.errors) {
      counts[error.error] = (counts[error.error] || 0) + 1;
    }

    return Object.entries(counts)
      .sort((a, b) => b[1] - a[1])[0];
  }
}

Debugging Checklist

When encountering errors, check:

API key is valid and properly formatted
Request payload matches schema requirements
Parameter values are within allowed ranges
Account has sufficient credits
Model name is correct and supported
Network connectivity is stable
Timeout values are appropriate
Error handling is implemented
Retry logic is in place

Create Response

Main endpoint documentation

Auto Routing

Automatic provider/model routing

Rate Limits

Understanding rate limits

Support

Contact support for help

Responses

Chat Completions (Beta)

Messages (Beta)

Models API

Features

Utilities

Reference

Catalog

Overview

Error Response Format

Status Codes

Error Types

400 Bad Request

401 Unauthorized

402 Payment Required

424 Failed Dependency

429 Too Many Requests

500 Internal Server Error

503 Service Unavailable

504 Gateway Timeout

Best Practices

Error Monitoring

Debugging Checklist

Create Response

Auto Routing

Rate Limits

Support

​Overview

​Error Response Format

​Status Codes

​Error Types

​400 Bad Request

​401 Unauthorized

​402 Payment Required

​424 Failed Dependency

​429 Too Many Requests

​500 Internal Server Error

​503 Service Unavailable

​504 Gateway Timeout

​Best Practices

​Error Monitoring

​Debugging Checklist

​Related Documentation

Create Response

Auto Routing

Rate Limits

Support

Overview

Error Response Format

Status Codes

Error Types

400 Bad Request

401 Unauthorized

402 Payment Required

424 Failed Dependency

429 Too Many Requests

500 Internal Server Error

503 Service Unavailable

504 Gateway Timeout

Best Practices

Error Monitoring

Debugging Checklist

Related Documentation