Error Handling

Learn how to handle errors and edge cases when using the Finatic SDK.

Understanding how to handle errors is crucial for building robust applications with Finatic. This guide covers error handling patterns, common error types, and best practices.

Note: All Finatic methods return a standard response format. Familiarize yourself with the response structure before diving into error handling.

Error Response Structure

When an error occurs, the response looks like this:

{
success: null,
error: {
message: "Error description",
code?: "ERROR_CODE",
status?: 400,
details?: { /* additional error details */ }
},
warning: null
}

The error object contains:

message: Human-readable error description (always present)
code (optional): Machine-readable error code for programmatic handling
status (optional): HTTP status code (401, 404, 500, etc.)
details (optional): Additional context (validation errors, affected fields, etc.)

Basic Error Handling

Always check for errors before accessing data. Here's an example using listAccounts():

const result = await finatic.v1.listAccounts();

Then handle the response:

// TypeScript
if (result.success) {
// Handle success
const accounts = result.success.data;
console.log('Accounts:', accounts);
} else if (result.error) {
// Handle error
console.error('Error:', result.error.message);
console.error('Code:', result.error.code);
console.error('Status:', result.error.status);
}

# Python
if result.success:
# Handle success
accounts = result.success['data']
print(f"Accounts: {accounts}")
elif result.error:
# Handle error
print(f"Error: {result.error['message']}")
print(f"Code: {result.error.get('code')}")
print(f"Status: {result.error.get('status')}")

Error Types

Authentication Errors

Occur when authentication fails or tokens expire:

const result = await finatic.v1.listAccounts();

if (result.error?.code === 'AUTH_ERROR' || result.error?.status === 401) {
// Token expired or invalid
// Re-initialize the SDK or refresh the token
const newFinatic = await FinaticConnect.init(newToken);
}

Common causes:

Expired one-time token (Client SDK)
Invalid API key (Server SDK)
Session expired

Solution:

Client SDK: Get a new one-time token from your backend
Server SDK: Verify API key is correct and active

Validation Errors

Occur when request parameters are invalid:

const result = await finatic.v1.listOrders({ accountId: 'your-account-id' });

if (result.error?.status === 422) {
// Validation error
console.error('Validation failed:', result.error.message);
console.error('Details:', result.error.details);
}

Common causes:

Invalid parameter format
Missing required parameters
Parameter out of range

Solution:

Check parameter types and formats
Verify all required parameters are provided
Review the API reference for parameter requirements

Not Found Errors

Occur when requested resources don't exist:

const result = await finatic.getCompany({
companyId: 'non-existent-id'
});

if (result.error?.status === 404) {
// Resource not found
console.error('Company not found');
}

Common causes:

Invalid resource ID
Resource was deleted
Insufficient permissions

Solution:

Verify the resource ID is correct
Check user permissions
Handle gracefully in your UI

Rate Limit Errors

Occur when API rate limits are exceeded:

const result = await finatic.v1.listAccounts();

if (result.error?.status === 429) {
// Rate limited
const retryAfter = result.error.details?.retry_after;
console.log(`Rate limited. Retry after ${retryAfter} seconds`);

// Implement exponential backoff
await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
// Retry the request
}

Solution:

Implement exponential backoff
Respect Retry-After headers
Consider upgrading your subscription tier

Network Errors

Occur when network requests fail:

try {
const result = await finatic.v1.listAccounts();
} catch (error) {
// Network error (not an API error)
if (error instanceof TypeError && error.message.includes('fetch')) {
console.error('Network error:', error.message);
// Show user-friendly message
// Retry with exponential backoff
}
}

Common causes:

No internet connection
API server unreachable
Timeout

Solution:

Check network connectivity
Verify baseUrl is correct
Implement retry logic with timeouts

Error Handling Patterns

Helper Function

Create a reusable error handler:

function handleFinaticError(result: FinaticResponse<any>) {
  if (result.success) {
  return { success: true, data: result.success.data };
  }

  if (result.error) {
  const { message, code, status } = result.error;

  // Log error
  console.error(`Finatic Error [${code || status}]:`, message);

  // Handle specific error types
  switch (status) {
  case 401:
  return { success: false, error: 'Authentication failed. Please reconnect.' };
  case 404:
  return { success: false, error: 'Resource not found.' };
  case 429:
  return { success: false, error: 'Rate limit exceeded. Please try again later.' };
  default:
  return { success: false, error: message || 'An error occurred.' };
  }
  }

  return { success: false, error: 'Unknown error occurred.' };
  }

  // Usage
  const result = await finatic.v1.listAccounts();
  const handled = handleFinaticError(result);

Try-Catch for Network Errors

Wrap SDK calls in try-catch for network errors:

async function getAccountsSafely() {
try {
const result = await finatic.v1.listAccounts();

if (result.error) {
// API returned an error response
throw new Error(result.error.message);
}

return result.success?.data || [];
} catch (error) {
// Network error or other exception
console.error('Failed to get accounts:', error);
throw error;
}
}

Retry Logic

Implement retry logic for transient errors:

async function getAccountsWithRetry(maxRetries = 3) {
for (let i = 0; i < maxRetries; i++) { try { const result=await finatic.v1.listAccounts(); if (result.success) {
  return result.success.data; } // Don't retry on client errors (4xx) if (result.error?.status && result.error.status
  < 500) { throw new Error(result.error.message); } // Retry on server errors (5xx) or network errors if (i <
  maxRetries - 1) { await new Promise(resolve=> setTimeout(resolve, Math.pow(2, i) * 1000));
  continue;
  }

  throw new Error(result.error?.message || 'Request failed');
  } catch (error) {
  if (i === maxRetries - 1) throw error;
  await new Promise(resolve => setTimeout(resolve, Math.pow(2, i) * 1000));
  }
  }
  }
  ```

  ## Warning Messages

  Some responses may include warnings:

  ```typescript
  const result = await finatic.v1.listAccounts();

  if (result.warning && result.warning.length > 0) {
  result.warning.forEach(warning => {
  console.warn('Warning:', warning.message);
  // Handle warnings (e.g., show to user, log)
  });
  }
  ```

  Warnings don't indicate failure but may provide important information about:
  - Deprecated features
  - Rate limit approaching
  - Data freshness
  - Partial results

  ## Best Practices

  1. **Always check for errors** - Never assume a request succeeded
  2. **Provide user-friendly messages** - Translate technical errors to user-friendly language
  3. **Log errors appropriately** - Log full error details for debugging, show simplified messages to users
  4. **Handle edge cases** - Account for network failures, timeouts, and unexpected responses
  5. **Implement retry logic** - For transient errors (network, rate limits)
  6. **Don't retry on client errors** - 4xx errors won't succeed on retry
  7. **Respect rate limits** - Implement backoff and respect `Retry-After` headers

  ## Common Error Scenarios

  ### Session Not Initialized

  ```typescript
  // Error: "Session not initialized"
  // Solution: Ensure SDK is initialized with init()
  const finatic = await FinaticConnect.init(oneTimeToken);
  ```

  ### Invalid Token

  ```typescript
  // Error: "Invalid token" or 401 status
  // Solution: Get a new one-time token from your backend
  const newToken = await fetch('/api/get-token').then(r => r.json());
  const finatic = await FinaticConnect.init(newToken.token);
  ```

  ### No Broker Connections

  ```typescript
  // Error: "No broker connections found"
  // Solution: User needs to connect a broker first
  await finatic.openPortal({ mode: 'dark' });
  ```

  ## Next Steps

  1. **[Standard Response Object](/docs/quick-start/standard-response-object)** - Review the response format in
  detail.
  2. **[Getting Data](/docs/quick-start/getting-data)** - Learn how to retrieve accounts, orders, and positions.
  3. **[Connecting Brokers](/docs/quick-start/connecting-brokers)** - Learn how to connect broker accounts.
  4. **[API Reference](/docs/api-reference)** - See all available methods and their error responses.