Standard Response Object

Understanding the consistent response format used across all Finatic SDK methods.

All Finatic SDK methods return a consistent, predictable response format. This standardization makes error handling and data access straightforward across your application.

Response Structure

Every SDK method returns an object with three properties:

{
  success: {
    data: { ... },
    meta: { ... }
  },
  error: { ... } | null,
  warning: { ... } | null
}

At any given time:

Either success or error will be populated, never both
warning may be present alongside either success or error

Success Response

When a request succeeds, the success property contains your data:

{
  success: {
    data: { /* your data */ },
    meta?: { /* optional metadata */ }
  },
  error: null,
  warning: null
}

Success Properties

data: The actual response data (accounts, orders, positions, etc.)
meta (optional): Additional metadata about the response (pagination info, timestamps, etc.)

Success Example

const result = await finatic.getAccounts();

if (result.success) {
  const accounts = result.success.data;
  console.log('Accounts:', accounts);
  
  // Access metadata if available
  if (result.success.meta) {
    console.log('Metadata:', result.success.meta);
  }
}

Error Response

When a request fails, the error property contains details about what went wrong:

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

Error Properties

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

Error Example

const result = await finatic.getAccounts();

if (result.error) {
  console.error('Error:', result.error.message);
  console.error('Code:', result.error.code);
  console.error('Status:', result.error.status);
  
  // Handle specific errors
  if (result.error.details) {
    console.error('Details:', result.error.details);
  }
}

Warning Messages

Some responses may include warnings alongside successful results:

{
  success: {
    data: { /* your data */ },
    meta?: { /* optional metadata */ }
  },
  error: null,
  warning: [
    {
      message: "Warning description",
      code?: "WARNING_CODE"
    }
  ]
}

Warnings don't indicate failure but provide important information about:

Deprecated features being used
Rate limits approaching
Data freshness concerns
Partial results returned

Warning Example

const result = await finatic.getAccounts();

if (result.success) {
  const accounts = result.success.data;
  
  // Check for warnings
  if (result.warning && result.warning.length > 0) {
    result.warning.forEach(warning => {
      console.warn('Warning:', warning.message);
      if (warning.code) {
        console.warn('Code:', warning.code);
      }
    });
  }
}

Basic Response Handling

Always check which property is populated before accessing data:

const result = await finatic.getAccounts();

if (result.success) {
  // Handle success - data is available
  const accounts = result.success.data;
  processAccounts(accounts);
} else if (result.error) {
  // Handle error - something went wrong
  console.error('Failed:', result.error.message);
  showErrorToUser(result.error);
}

Paginated Data

Methods that return lists (getAccounts(), getOrders(), getPositions()) return paginated data. The data property is a PaginatedData object that behaves like an array but includes navigation methods:

const result = await finatic.getOrders({ limit: 50 });

if (result.success) {
  const orders = result.success.data; // PaginatedData object
  
  // Use as array
  console.log(`Found ${orders.length} orders`);
  orders.forEach(order => console.log(order.symbol));
  
  // Check for more pages
  if (orders.hasMore) {
    // Navigate to next page
    const nextPage = await orders.nextPage();
    console.log(`Next page: ${nextPage.length} orders`);
  }
}

For more details on pagination, see Getting Data - Pagination.

Type Safety (TypeScript)

The response format is fully typed in TypeScript:

import { FinaticResponse } from '@finatic/client-sdk';

// Response types are inferred
const result = await finatic.getAccounts();
// result is FinaticResponse<Account[]>

if (result.success) {
  // TypeScript knows data is Account[]
  const accounts = result.success.data;
  accounts.forEach(account => {
    console.log(account.id); // ✓ Type-safe
  });
}

if (result.error) {
  // TypeScript knows error properties
  const message: string = result.error.message;
  const status: number | undefined = result.error.status;
}

Common Status Codes

Understanding HTTP status codes helps with error handling:

Status	Meaning	Action
200	Success	Data available in `success.data`
400	Bad Request	Check request parameters
401	Unauthorized	Re-authenticate or refresh token
403	Forbidden	Check permissions
404	Not Found	Resource doesn't exist
422	Validation Error	Fix invalid parameters
429	Rate Limited	Implement backoff, retry later
500	Server Error	Retry with exponential backoff
503	Service Unavailable	Service temporarily down, retry later

Best Practices

Always check for errors first - Prevents accessing undefined data
1if (result.error) { 2 handleError(result.error); 3 return; 4} 5// Now safely access result.success 6
Don't assume success - Always verify the response state
1// ❌ Bad - assumes success 2const accounts = result.success.data; 3 4// ✅ Good - checks first 5if (result.success) { 6 const accounts = result.success.data; 7} 8
Handle warnings - Don't ignore important information
1if (result.warning) { 2 logWarnings(result.warning); 3} 4
Use type guards - Leverage TypeScript's type narrowing
1if (result.success) { 2 // TypeScript narrows the type here 3 const data = result.success.data; 4} 5

Next Steps

Getting Data - Learn how to retrieve accounts, orders, and positions
Error Handling - Detailed guide on handling errors and edge cases
API Reference - Explore all available methods