Errors

AssistantRouter uses conventional HTTP response codes to indicate the success or failure of an API request.

HTTP Status Codes

Code	Description
`200`	Success
`400`	Bad Request - Invalid parameters or validation error
`401`	Unauthorized - Invalid or missing API key
`402`	Payment Required - Insufficient balance
`403`	Forbidden - Insufficient permissions or tier limits
`404`	Not Found - Resource doesn't exist
`409`	Conflict - Resource already exists
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error
`503`	Service Unavailable
`504`	Gateway Timeout

Error Response Format

All errors return a JSON object with the following structure:

{
  "error": {
    "type": "error_type",
    "message": "A human-readable description of the error",
    "code": "specific_error_code",
    "param": "field_name"
  }
}

Field	Description
`type`	The error category (see Error Types below)
`message`	A human-readable description of the error
`code`	Optional machine-readable error code for specific conditions
`param`	Optional field name that caused the error (for validation errors)

Every response includes an X-Request-ID header with a unique request identifier for debugging.

Error Types

Authentication & Authorization

`authentication_error` (401)

Authentication failed due to invalid or missing credentials.

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

`authorization_error` (403)

Valid authentication but insufficient permissions.

{
  "error": {
    "type": "authorization_error",
    "message": "You don't have permission to access this resource"
  }
}

Resource Errors

`not_found` (404)

The requested resource doesn't exist.

{
  "error": {
    "type": "not_found",
    "message": "Assistant with ID 'asst_xxx' not found"
  }
}

`already_exists` (409)

Attempted to create a resource that already exists.

{
  "error": {
    "type": "already_exists",
    "message": "A conversation with this external_id already exists"
  }
}

`conflict` (409)

The request conflicts with current state.

{
  "error": {
    "type": "conflict",
    "message": "Cannot delete assistant while it has active conversations"
  }
}

Validation Errors

`validation_error` (400)

Request failed validation.

{
  "error": {
    "type": "validation_error",
    "message": "Either assistant_id or model is required",
    "param": "model"
  }
}

`bad_request` (400)

The request was malformed or invalid.

{
  "error": {
    "type": "bad_request",
    "message": "Request body must be valid JSON"
  }
}

Rate Limiting

`rate_limit_exceeded` (429)

Too many requests in a given time period.

{
  "error": {
    "type": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please slow down.",
    "remaining_requests": 0,
    "reset_at": "2024-01-15T10:31:00Z"
  }
}

`tier_limit_exceeded` (403)

A tier-specific limit has been exceeded.

{
  "error": {
    "type": "tier_limit_exceeded",
    "message": "You've reached the maximum number of assistants for your tier (1). Upgrade to Pro for more.",
    "limit": 1,
    "current": 1
  }
}

Billing & Quota

`insufficient_balance` (402)

The workspace doesn't have enough credits.

{
  "error": {
    "type": "insufficient_balance",
    "message": "Insufficient balance. Please add credits to your wallet.",
    "required_cents": 10,
    "available_cents": 5
  }
}

Add credits in the Dashboard to resolve this error.

`budget_exceeded` (403)

A budget limit has been reached.

{
  "error": {
    "type": "budget_exceeded",
    "message": "Daily budget exceeded for this assistant"
  }
}

`quota_exceeded` (403)

A usage quota has been exceeded.

{
  "error": {
    "type": "quota_exceeded",
    "message": "Monthly token quota exceeded"
  }
}

Server Errors

`internal_error` (500)

Something went wrong on our end.

{
  "error": {
    "type": "internal_error",
    "message": "An internal error occurred. Please try again."
  }
}

`service_unavailable` (503)

The service is temporarily unavailable.

{
  "error": {
    "type": "service_unavailable",
    "message": "The service is temporarily unavailable. Please try again later."
  }
}

`timeout` (504)

The request timed out.

{
  "error": {
    "type": "timeout",
    "message": "The request timed out. Please try again."
  }
}

Error Types Summary

Type	HTTP Code	Description
`authentication_error`	401	Invalid or missing API key
`authorization_error`	403	Valid key but insufficient permissions
`not_found`	404	Resource doesn't exist
`already_exists`	409	Resource already exists
`conflict`	409	Request conflicts with current state
`validation_error`	400	Request failed validation
`bad_request`	400	Malformed request
`rate_limit_exceeded`	429	Too many requests
`tier_limit_exceeded`	403	Tier-specific limit exceeded
`insufficient_balance`	402	Not enough credits
`budget_exceeded`	403	Budget limit reached
`quota_exceeded`	403	Usage quota exceeded
`internal_error`	500	Server error
`service_unavailable`	503	Service temporarily down
`timeout`	504	Request timed out

Handling Errors

Always handle errors gracefully in your application.

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://api.assistantrouter.com/v1',
  apiKey: process.env.ASSISTANTROUTER_API_KEY,
});

try {
  const response = await client.chat.completions.create({
    // @ts-ignore - assistant_id is our extension
    assistant_id: 'your-assistant-uuid',
    messages: [{ role: 'user', content: 'Hello!' }],
  });
} catch (error) {
  if (error instanceof OpenAI.APIError) {
    const errorBody = error.error as { type: string; message: string };

    switch (errorBody.type) {
      case 'insufficient_balance':
        // Prompt user to add credits
        console.log('Please add credits to continue');
        break;
      case 'rate_limit_exceeded':
        // Implement exponential backoff
        await new Promise(r => setTimeout(r, 1000));
        break;
      case 'tier_limit_exceeded':
        // Suggest upgrade
        console.log('Consider upgrading your plan');
        break;
      default:
        // Log and show generic error
        console.error(errorBody.message);
    }
  }
}

Errors

AssistantRouter uses conventional HTTP response codes to indicate the success or failure of an API request.

HTTP Status Codes

Code	Description
`200`	Success
`400`	Bad Request - Invalid parameters or validation error
`401`	Unauthorized - Invalid or missing API key
`402`	Payment Required - Insufficient balance
`403`	Forbidden - Insufficient permissions or tier limits
`404`	Not Found - Resource doesn't exist
`409`	Conflict - Resource already exists
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error
`503`	Service Unavailable
`504`	Gateway Timeout

Error Response Format

All errors return a JSON object with the following structure:

{
  "error": {
    "type": "error_type",
    "message": "A human-readable description of the error",
    "code": "specific_error_code",
    "param": "field_name"
  }
}

Field	Description
`type`	The error category (see Error Types below)
`message`	A human-readable description of the error
`code`	Optional machine-readable error code for specific conditions
`param`	Optional field name that caused the error (for validation errors)

Every response includes an X-Request-ID header with a unique request identifier for debugging.

Error Types

Authentication & Authorization

`authentication_error` (401)

Authentication failed due to invalid or missing credentials.

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

`authorization_error` (403)

Valid authentication but insufficient permissions.

{
  "error": {
    "type": "authorization_error",
    "message": "You don't have permission to access this resource"
  }
}

Resource Errors

`not_found` (404)

The requested resource doesn't exist.

{
  "error": {
    "type": "not_found",
    "message": "Assistant with ID 'asst_xxx' not found"
  }
}

`already_exists` (409)

Attempted to create a resource that already exists.

{
  "error": {
    "type": "already_exists",
    "message": "A conversation with this external_id already exists"
  }
}

`conflict` (409)

The request conflicts with current state.

{
  "error": {
    "type": "conflict",
    "message": "Cannot delete assistant while it has active conversations"
  }
}

Validation Errors

`validation_error` (400)

Request failed validation.

{
  "error": {
    "type": "validation_error",
    "message": "Either assistant_id or model is required",
    "param": "model"
  }
}

`bad_request` (400)

The request was malformed or invalid.

{
  "error": {
    "type": "bad_request",
    "message": "Request body must be valid JSON"
  }
}

Rate Limiting

`rate_limit_exceeded` (429)

Too many requests in a given time period.

{
  "error": {
    "type": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please slow down.",
    "remaining_requests": 0,
    "reset_at": "2024-01-15T10:31:00Z"
  }
}

`tier_limit_exceeded` (403)

A tier-specific limit has been exceeded.

{
  "error": {
    "type": "tier_limit_exceeded",
    "message": "You've reached the maximum number of assistants for your tier (1). Upgrade to Pro for more.",
    "limit": 1,
    "current": 1
  }
}

Billing & Quota

`insufficient_balance` (402)

The workspace doesn't have enough credits.

{
  "error": {
    "type": "insufficient_balance",
    "message": "Insufficient balance. Please add credits to your wallet.",
    "required_cents": 10,
    "available_cents": 5
  }
}

Add credits in the Dashboard to resolve this error.

`budget_exceeded` (403)

A budget limit has been reached.

{
  "error": {
    "type": "budget_exceeded",
    "message": "Daily budget exceeded for this assistant"
  }
}

`quota_exceeded` (403)

A usage quota has been exceeded.

{
  "error": {
    "type": "quota_exceeded",
    "message": "Monthly token quota exceeded"
  }
}

Server Errors

`internal_error` (500)

Something went wrong on our end.

{
  "error": {
    "type": "internal_error",
    "message": "An internal error occurred. Please try again."
  }
}

`service_unavailable` (503)

The service is temporarily unavailable.

{
  "error": {
    "type": "service_unavailable",
    "message": "The service is temporarily unavailable. Please try again later."
  }
}

`timeout` (504)

The request timed out.

{
  "error": {
    "type": "timeout",
    "message": "The request timed out. Please try again."
  }
}

Error Types Summary

Type	HTTP Code	Description
`authentication_error`	401	Invalid or missing API key
`authorization_error`	403	Valid key but insufficient permissions
`not_found`	404	Resource doesn't exist
`already_exists`	409	Resource already exists
`conflict`	409	Request conflicts with current state
`validation_error`	400	Request failed validation
`bad_request`	400	Malformed request
`rate_limit_exceeded`	429	Too many requests
`tier_limit_exceeded`	403	Tier-specific limit exceeded
`insufficient_balance`	402	Not enough credits
`budget_exceeded`	403	Budget limit reached
`quota_exceeded`	403	Usage quota exceeded
`internal_error`	500	Server error
`service_unavailable`	503	Service temporarily down
`timeout`	504	Request timed out

Handling Errors

Always handle errors gracefully in your application.

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://api.assistantrouter.com/v1',
  apiKey: process.env.ASSISTANTROUTER_API_KEY,
});

try {
  const response = await client.chat.completions.create({
    // @ts-ignore - assistant_id is our extension
    assistant_id: 'your-assistant-uuid',
    messages: [{ role: 'user', content: 'Hello!' }],
  });
} catch (error) {
  if (error instanceof OpenAI.APIError) {
    const errorBody = error.error as { type: string; message: string };

    switch (errorBody.type) {
      case 'insufficient_balance':
        // Prompt user to add credits
        console.log('Please add credits to continue');
        break;
      case 'rate_limit_exceeded':
        // Implement exponential backoff
        await new Promise(r => setTimeout(r, 1000));
        break;
      case 'tier_limit_exceeded':
        // Suggest upgrade
        console.log('Consider upgrading your plan');
        break;
      default:
        // Log and show generic error
        console.error(errorBody.message);
    }
  }
}

Errors

On this page

Errors

On this page