Skip to main content

​
GraphyApiError

All API errors are wrapped in GraphyApiError. Each error carries structured metadata you can use to decide how to handle the failure: 
import { isGraphyApiError } from '@graphysdk/agents-sdk';

try {
  const result = await ai.generateGraph({ config, userPrompt });
} catch (error) {
  if (isGraphyApiError(error)) {
    console.error(`[${error.code}] ${error.message} (HTTP ${error.status})`);
    if (error.retryable) {
      // schedule retry
    }
  }
}
PropertyTypeDescription
messagestringHuman-readable error description
statusnumber | undefinedHTTP status code, if from an HTTP response
codestring | undefinedMachine-readable error code from the API
retryablebooleanWhether the SDK considers this error retryable
Use the isGraphyApiError() type guard to safely narrow unknown errors. See the Type Reference for the full class definition.

​
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 retryable: true: 
try {
  const result = await ai.generateGraph({ config, userPrompt });
} catch (error) {
  if (isGraphyApiError(error) && error.retryable) {
    console.error('Transient error, consider retrying');
  }
}

​
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 instanceof Error && error.name === 'AbortError') {
    // User cancelled - not an error
    return;
  }
  throw error;
}

​
Stream Errors

In streaming mode, errors can arrive as events: 
import { isErrorEvent } from '@graphysdk/agents-sdk';

for await (const event of stream) {
  if (isErrorEvent(event)) {
    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: 
import { isGraphyApiError } from '@graphysdk/agents-sdk';

try {
  for await (const event of stream) {
    // ...
  }
} catch (error) {
  if (error instanceof Error && error.name === 'AbortError') {
    return; // User cancelled
  }
  if (isGraphyApiError(error)) {
    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 instanceof Error && error.name === 'AbortError') {
    console.error('Request timed out');
  }
}

​
Best Practices

​
Log errors with context

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

​
Show user-friendly messages

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