Best Practices

Follow these best practices to build secure, performant, and reliable integrations with our API.

Security

Protect Your API Keys

Never expose API keys in client-side code or public repositories
Use environment variables to store sensitive credentials
Rotate keys regularly and revoke unused keys
Use restricted keys with minimal permissions when possible

// Good: Load from environment
const client = new Client({
  apiKey: process.env.API_KEY
});

// Bad: Hardcoded key
const client = new Client({
  apiKey: 'sk_live_abc123...' // Never do this!
});

Validate Webhooks

Always verify webhook signatures before processing. See ourwebhooks documentation for details.

Performance

Use Efficient Pagination

Request only the data you need with appropriate page sizes
Use the maximum limit when fetching all records
Cache results when appropriate to reduce API calls

Batch Operations

When creating or updating multiple resources, use batch endpoints when available instead of making individual requests:

// Good: Batch create (single request)
await client.users.createMany([
  { email: 'user1@example.com', name: 'User 1' },
  { email: 'user2@example.com', name: 'User 2' },
  { email: 'user3@example.com', name: 'User 3' },
]);

// Bad: Individual creates (multiple requests)
await client.users.create({ email: 'user1@example.com', name: 'User 1' });
await client.users.create({ email: 'user2@example.com', name: 'User 2' });
await client.users.create({ email: 'user3@example.com', name: 'User 3' });

Reliability

Implement Retry Logic

Network issues happen. Implement exponential backoff for transient failures:

async function withRetry<T>(
  fn: () => Promise<T>,
  maxRetries = 3
): Promise<T> {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      const isRetryable = 
        error.status === 429 || 
        error.status >= 500;
      
      if (!isRetryable || attempt === maxRetries - 1) {
        throw error;
      }
      
      const delay = Math.pow(2, attempt) * 1000;
      await new Promise(r => setTimeout(r, delay));
    }
  }
  throw new Error('Unreachable');
}

Only retry on 5xx errors and 429 rate limits. Don't retry 4xx client errors as they will continue to fail.

Handle Idempotency

For critical operations, use idempotency keys to safely retry requests without creating duplicates:

const order = await client.orders.create(
  { customerId: 'usr_123', items: [...] },
  { idempotencyKey: 'order-abc-123' }
);

Debugging

Enable Debug Mode

During development, enable debug mode to see detailed logs:

const client = new Client({
  apiKey: process.env.API_KEY,
  debug: process.env.NODE_ENV === 'development'
});

Track Request IDs

Every response includes a unique X-Request-ID header. Log these for debugging and support requests.

When contacting support, always include the request ID to help us quickly identify and resolve issues.