Error Handling

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

Error	Status	Description
`BadRequestError`	400	Invalid request parameters
`AuthenticationError`	401	Missing or invalid API key
`PermissionDeniedError`	403	Insufficient permissions
`NotFoundError`	404	Resource not found
`ConflictError`	409	Resource conflict (e.g., duplicate space name)
`UnprocessableEntityError`	422	Validation error
`RateLimitError`	429	Too many requests
`InternalServerError`	5xx	Server 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.

Getting Started

MCP Server

AI Tool Setup

CLI

TypeScript SDK

Error Types

Basic Error Handling

Error Types Reference

Rate Limit Handling

Error Properties

RateLimitError Properties

Type-Safe Error Handling

Common Error Scenarios

Invalid API Key

Resource Not Found

Validation Errors

Network Issues

Error Handling Best Practices

Handle Specific Errors

Retry Rate Limits

Log Errors

Graceful Degradation

Next Steps

Usage Guide

AI Integration

Quickstart

API Reference

​Error Types

​Basic Error Handling

​Error Types Reference

​Rate Limit Handling

​Error Properties

​RateLimitError Properties

​Type-Safe Error Handling

​Common Error Scenarios

​Invalid API Key

​Resource Not Found

​Validation Errors

​Network Issues

​Error Handling Best Practices

Handle Specific Errors

Retry Rate Limits

Log Errors

Graceful Degradation

​Next Steps

Usage Guide

AI Integration

Quickstart

API Reference

Error Types

Basic Error Handling

Error Types Reference

Rate Limit Handling

Error Properties

RateLimitError Properties

Type-Safe Error Handling

Common Error Scenarios

Invalid API Key

Resource Not Found

Validation Errors

Network Issues

Error Handling Best Practices

Next Steps