Skip to main content

​
GraphyApiError

All API errors are wrapped in GraphyApiError: 
import { GraphyApiError } from '@graphysdk/ai';

try {
  const result = await ai.generateGraph({ config, userPrompt });
} catch (error) {
  if (error instanceof GraphyApiError) {
    console.error('API error:', error.message);
  }
}

​
Retry Behavior

The SDK automatically retries failed requests based on retryConfig. Default configuration: 
{
  attempts: 3,
  delay: 1000,
  backoff: 2
}
Retry delay formula: 
delay * (backoff ^ (attempt - 1))
With defaults:
AttemptDelay
1Immediate
21000ms
32000ms

​
Retryable Conditions

ConditionRetries
HTTP 5xxYes
HTTP 429 (rate limit)Yes
Network failureYes
HTTP 4xx (except 429)No
User abortNo
GraphyApiErrorNo

​
Custom Retry Configuration

const ai = new GraphyAiSdk({
  apiKey: process.env.GRAPHY_API_KEY,
  baseUrl: 'https://agents.graphy.dev',
  retryConfig: {
    attempts: 5,      // More attempts
    delay: 500,       // Shorter initial delay
    backoff: 1.5,     // Gentler backoff
  },
});

​
Disable Retries

const ai = new GraphyAiSdk({
  apiKey: process.env.GRAPHY_API_KEY,
  baseUrl: 'https://agents.graphy.dev',
  retryConfig: {
    attempts: 1,  // No retries
    delay: 0,
    backoff: 1,
  },
});

​
Error Codes

Errors from the API include a code field:
CodeHTTP StatusRetryableDescription
VALIDATION_ERROR400NoInvalid request body or parameters
AUTHENTICATION_ERROR401NoInvalid or missing API key
RATE_LIMIT_ERROR429YesToo many requests
PROCESSING_ERROR500YesInternal processing failure
TIMEOUT_ERROR504YesRequest took too long

​
Network Errors

Network failures throw a GraphyApiError with message "Network error": 
try {
  const result = await ai.generateGraph({ config, userPrompt });
} catch (error) {
  if (error instanceof GraphyApiError && error.message === 'Network error') {
    console.error('Network connectivity issue');
  }
}

​
Abort Errors

User cancellation throws a native AbortError: 
const controller = new AbortController();

try {
  const result = await ai.generateGraph(
    { config, userPrompt },
    undefined,
    controller.signal
  );
} catch (error) {
  if (error.name === 'AbortError') {
    // User cancelled - not an error
    return;
  }
  throw error;
}

​
Stream Errors

In streaming mode, errors can arrive as events: 
for await (const event of stream) {
  if (event.type === 'error') {
    console.error('Error:', event.error);
    console.error('Code:', event.code);
    console.error('Retryable:', event.retryable);

    if (event.retryable) {
      // Implement retry logic
    }
    return;
  }
}
Or as exceptions when the stream fails: 
try {
  for await (const event of stream) {
    // ...
  }
} catch (error) {
  if (error.name === 'AbortError') {
    return; // User cancelled
  }
  if (error instanceof GraphyApiError) {
    console.error('API error:', error.message);
  }
}

​
Timeout Errors

The SDK throws AbortError when a request exceeds the configured timeout: 
const ai = new GraphyAiSdk({
  apiKey: process.env.GRAPHY_API_KEY,
  baseUrl: 'https://agents.graphy.dev',
  timeout: 10000, // 10 seconds
});

try {
  const result = await ai.generateGraph({ config, userPrompt });
} catch (error) {
  if (error.name === 'AbortError') {
    console.error('Request timed out');
  }
}

​
Best Practices

​
Log errors with context

try {
  const result = await ai.generateGraph({ config, userPrompt });
} catch (error) {
  logger.error('generateGraph failed', {
    error: error.message,
    userPrompt,
    configType: config.type,
  });
  throw error;
}

​
Show user-friendly messages

function getErrorMessage(error: unknown): string {
  if (error instanceof GraphyApiError) {
    if (error.message.includes('401')) {
      return 'Authentication failed. Please check your API key.';
    }
    if (error.message.includes('429')) {
      return 'Too many requests. Please try again later.';
    }
    return 'Failed to generate chart. Please try again.';
  }
  if (error.name === 'AbortError') {
    return 'Request was cancelled.';
  }
  return 'An unexpected error occurred.';
}