Skip to main content
The Orchata SDK throws typed errors for different scenarios, making error handling straightforward and type-safe.

​
Error Types

Import error classes to handle specific error types: 
import {
  Orchata,
  OrchataError,
  AuthenticationError,
  NotFoundError,
  RateLimitError,
  BadRequestError,
  PermissionDeniedError,
  ConflictError,
  UnprocessableEntityError,
  InternalServerError,
  TimeoutError,
  ConnectionError
} from '@orchata-ai/sdk';

​
Basic Error Handling

Handle errors with try-catch blocks: 
import { Orchata, AuthenticationError, NotFoundError } from '@orchata-ai/sdk';

const client = new Orchata({ apiKey: 'oai_xxx' });

try {
  const { results } = await client.query({
    spaceIds: 'space_123',
    query: 'test'
  });
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid API key');
  } else if (error instanceof NotFoundError) {
    console.error('Space not found');
  } else if (error instanceof RateLimitError) {
    console.error(`Rate limited. Retry after ${error.retryAfter} seconds`);
  } else if (error instanceof OrchataError) {
    console.error(`API error: ${error.message} (${error.status})`);
  } else {
    throw error; // Re-throw unknown errors
  }
}

​
Error Types Reference

ErrorStatusDescription
BadRequestError400Invalid request parameters
AuthenticationError401Missing or invalid API key
PermissionDeniedError403Insufficient permissions
NotFoundError404Resource not found
ConflictError409Resource conflict (e.g., duplicate space name)
UnprocessableEntityError422Validation error
RateLimitError429Too many requests
InternalServerError5xxServer error
TimeoutError-Request timeout
ConnectionError-Network connectivity issue

​
Rate Limit Handling

Handle rate limits with retry logic: 
import { Orchata, RateLimitError } from '@orchata-ai/sdk';

async function queryWithRetry(client: Orchata, query: string, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await client.query({
        spaceIds: 'space_123',
        query
      });
    } catch (error) {
      if (error instanceof RateLimitError) {
        const waitTime = error.retryAfter * 1000; // Convert to milliseconds
        console.log(`Rate limited. Waiting ${waitTime}ms before retry...`);
        await new Promise(resolve => setTimeout(resolve, waitTime));
        continue;
      }
      throw error; // Re-throw non-rate-limit errors
    }
  }
  throw new Error('Max retries exceeded');
}

​
Error Properties

All error instances include useful properties: 
try {
  await client.spaces.get('invalid_id');
} catch (error) {
  if (error instanceof OrchataError) {
    console.error(error.message); // Human-readable error message
    console.error(error.status); // HTTP status code
    console.error(error.statusCode); // Alias for status
    console.error(error.code); // Error code (if available)
  }
}

​
RateLimitError Properties

RateLimitError includes additional properties: 
if (error instanceof RateLimitError) {
  console.error(error.retryAfter); // Seconds to wait before retrying
  console.error(error.limit); // Rate limit value
  console.error(error.remaining); // Remaining requests
  console.error(error.reset); // Timestamp when limit resets
}

​
Type-Safe Error Handling

TypeScript provides full type safety for error handling: 
import { Orchata, OrchataError } from '@orchata-ai/sdk';

async function safeQuery(client: Orchata, query: string) {
  try {
    const result = await client.query({
      spaceIds: 'space_123',
      query
    });
    return { success: true, data: result };
  } catch (error) {
    if (error instanceof OrchataError) {
      return {
        success: false,
        error: {
          message: error.message,
          status: error.status,
          code: error.code
        }
      };
    }
    return {
      success: false,
      error: {
        message: 'Unknown error',
        status: 0
      }
    };
  }
}

​
Common Error Scenarios

​
Invalid API Key

try {
  const client = new Orchata({ apiKey: 'invalid_key' });
  await client.spaces.list();
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Please check your API key');
  }
}

​
Resource Not Found

try {
  await client.spaces.get('nonexistent_space');
} catch (error) {
  if (error instanceof NotFoundError) {
    console.error('Space does not exist or you do not have access');
  }
}

​
Validation Errors

try {
  await client.spaces.create({
    name: '', // Invalid: empty name
    description: 'Test'
  });
} catch (error) {
  if (error instanceof UnprocessableEntityError) {
    console.error('Validation failed:', error.message);
  }
}

​
Network Issues

try {
  await client.query({ spaceIds: 'space_123', query: 'test' });
} catch (error) {
  if (error instanceof ConnectionError) {
    console.error('Network error. Check your connection.');
  } else if (error instanceof TimeoutError) {
    console.error('Request timed out. Try again later.');
  }
}

​
Error Handling Best Practices

Handle Specific Errors

Catch specific error types to provide better user feedback and handle each case appropriately.

Retry Rate Limits

Implement retry logic for RateLimitError using the retryAfter property.

Log Errors

Log errors with context (request details, user ID, etc.) for debugging.

Graceful Degradation

Provide fallback behavior when errors occur (e.g., show cached data or default message).

​
Next Steps

Usage Guide

Learn about Spaces, Documents, and Queries APIs.

AI Integration

Integrate with Vercel AI SDK for AI-powered applications.

Quickstart

Review the quickstart guide.

API Reference

Explore the REST API documentation.