How to Manage Multiple API Integrations Efficiently

Most SaaS products integrate with dozens of third-party APIs. Stripe for payments, Twilio for messaging, Salesforce for CRM, Slack for notifications, GitHub for source control, AWS services for infrastructure, and a long tail of specialized tools that grow with every product sprint. Each new integration feels simple in isolation. The problem compounds when you have twenty of them.

This guide covers the practical engineering work of managing multiple API integrations at scale — authentication differences, rate limiting, retries, error normalization, versioning, monitoring, and how modern AI tooling via the Model Context Protocol changes the equation.

Why Multiple API Integrations Break Down

Before prescribing solutions, it is worth naming the real failure modes. These are the ones that cost teams the most time in practice.

Authentication Sprawl

Every API authenticates differently. Stripe uses Bearer tokens. GitHub offers OAuth 2.0, personal access tokens, and GitHub App JWT flows. Salesforce requires OAuth with a PKCE flow and separate refresh token management. AWS uses SigV4 request signing. Twilio uses HTTP Basic Auth with an Account SID and Auth Token. Slack uses Bot Tokens scoped to workspaces.

Without a central credential management strategy, credentials end up scattered across environment variables in CI systems, hardcoded in config files committed to repositories, stored inconsistently across microservices, and rotated manually when someone remembers. The result is credential leakage, stale tokens causing silent failures, and authentication logic reimplemented by every developer who touches a new integration.

Rate Limit Handling Done Per-Integration

Almost every production API has rate limits, but they are expressed differently. Stripe measures requests per second per API key. GitHub measures requests per hour per OAuth token, with separate limits for search endpoints. Salesforce counts API calls against a daily limit that resets at midnight in your org's timezone. Twilio throttles at the message-per-second level with burst allowances. OpenAI limits by tokens per minute and requests per minute, separately.

Teams that handle this ad hoc end up with each integration having its own backoff logic, often written differently by different engineers, tested inconsistently, and silently failing in production when a limit is hit at an unexpected time.

Retry Logic Inconsistency

Related but distinct from rate limits: transient failures — 503s, connection timeouts, network blips — need to be retried. Permanent failures — 400 Bad Request, 401 Unauthorized — should not be retried. 429s (rate limits) need exponential backoff with jitter. 503s need backoff too, but with different parameters. Most teams apply this logic inconsistently, leading to cascading failures during incidents and unnecessary noise in error tracking.

Error Model Differences

Stripe returns structured error objects with type, code, and decline_code fields. GitHub returns message strings with sometimes-present errors arrays. Salesforce returns SOAP-style fault objects even in its REST API. AWS returns XML errors in some services and JSON in others. Twilio wraps errors in a code/message/more_info structure.

When your application code has to handle all of these differently, debugging cross-service failures becomes genuinely hard. Your on-call engineer at 2am is chasing a bug through four different error formats.

Versioning and Breaking Changes

APIs change. Stripe has versioned its API for years and maintains backward compatibility with version pinning. Twitter/X has broken its API contract several times without warning. Salesforce deprecates API versions on a release cycle. GitHub adds required fields, changes response shapes, and deprecates OAuth scopes.

Without explicit version pinning and a process for tracking upstream changes, a provider's API update silently breaks your integration in production.

Maintenance Cost Accumulates Non-Linearly

Two integrations are manageable. Five is fine. Twenty is where teams start feeling the pain. The maintenance cost of multiple integrations does not scale linearly — it scales closer to O(n²) because of the cross-cutting concerns: every authentication change affects every integration, every monitoring alert needs per-provider tuning, and every on-call rotation requires familiarity with all providers.

The Core Solution: Centralize and Abstract

The antidote to integration sprawl is a combination of centralized infrastructure and a consistent abstraction layer. This is not a new idea — it is what API gateways, service meshes, and integration platforms do. The difference for teams building their own is making the right architectural decisions before the codebase grows.

Build an Internal Integration Hub

An integration hub is simply a dedicated module, service, or set of packages that owns all third-party API logic. Your application code never calls axios.get('https://api.stripe.com/...') directly. It calls payments.createCustomer(...). The integration hub handles credentials, transport, retries, rate limiting, and error normalization.

This can be implemented as:

• A shared internal library (monorepo package) — good for single-service architectures or tightly coupled microservices.
• A dedicated internal service — good when multiple services need the same integrations, or when you want independent deployability and credential isolation.
• A sidecar pattern — good for Kubernetes-based architectures where each service gets a co-located proxy that handles outbound API calls.

For most teams under 50 engineers, a well-organized shared library is sufficient and simpler to operate than a separate service.

Centralize Authentication: The Credential Provider Pattern

Every integration should obtain credentials through a single credential provider interface, not from environment variables directly.

// credential-provider.ts
export interface CredentialProvider {
  getCredential(integrationId: string): Promise<Credential>;
}

export interface Credential {
  type: 'bearer' | 'basic' | 'api-key' | 'oauth2' | 'aws-sigv4';
  value: string;
  expiresAt?: Date;
  metadata?: Record<string, string>;
}

// vault-credential-provider.ts
import { SecretsManagerClient, GetSecretValueCommand } from '@aws-sdk/client-secrets-manager';

export class VaultCredentialProvider implements CredentialProvider {
  private client: SecretsManagerClient;
  private cache = new Map<string, { credential: Credential; fetchedAt: number }>();
  private cacheTtlMs = 5 * 60 * 1000; // 5 minutes

  constructor(region: string) {
    this.client = new SecretsManagerClient({ region });
  }

  async getCredential(integrationId: string): Promise<Credential> {
    const cached = this.cache.get(integrationId);
    if (cached && Date.now() - cached.fetchedAt < this.cacheTtlMs) {
      return cached.credential;
    }

    const command = new GetSecretValueCommand({
      SecretId: `integrations/${integrationId}`,
    });
    const response = await this.client.send(command);
    const secret = JSON.parse(response.SecretString ?? '{}');

    const credential: Credential = {
      type: secret.type,
      value: secret.value,
      expiresAt: secret.expiresAt ? new Date(secret.expiresAt) : undefined,
    };

    this.cache.set(integrationId, { credential, fetchedAt: Date.now() });
    return credential;
  }
}

Key decisions in this pattern:

• Cache credentials in memory with a short TTL to avoid hammering your secrets store on every API request.
• Never log credential values. Log only integrationId and credential.type.
• Handle token expiry explicitly. If expiresAt is set and within 60 seconds, proactively refresh before the next request.
• Support multiple vault backends by keeping the interface generic. Teams migrate from one secrets manager to another; your integrations should not care.

Standardize HTTP Transport: Retry and Rate Limit Logic Once

Instead of every integration implementing its own retry logic, build a shared HTTP client that handles the common cases:

// resilient-http-client.ts
import axios, { AxiosInstance, AxiosRequestConfig, AxiosResponse } from 'axios';

export interface RetryConfig {
  maxAttempts: number;
  initialDelayMs: number;
  maxDelayMs: number;
  retryableStatusCodes: number[];
}

export const DEFAULT_RETRY_CONFIG: RetryConfig = {
  maxAttempts: 4,
  initialDelayMs: 500,
  maxDelayMs: 30_000,
  retryableStatusCodes: [429, 500, 502, 503, 504],
};

function withJitter(delayMs: number): number {
  return delayMs * (0.75 + Math.random() * 0.5);
}

function backoffDelay(attempt: number, config: RetryConfig): number {
  const exponential = config.initialDelayMs * Math.pow(2, attempt);
  return withJitter(Math.min(exponential, config.maxDelayMs));
}

export async function resilientRequest<T>(
  client: AxiosInstance,
  config: AxiosRequestConfig,
  retryConfig: RetryConfig = DEFAULT_RETRY_CONFIG,
  integrationId: string
): Promise<AxiosResponse<T>> {
  let lastError: unknown;

  for (let attempt = 0; attempt < retryConfig.maxAttempts; attempt++) {
    try {
      const response = await client.request<T>(config);
      return response;
    } catch (error: any) {
      lastError = error;
      const status = error?.response?.status;

      if (!status || !retryConfig.retryableStatusCodes.includes(status)) {
        // Non-retryable: 400, 401, 403, 404, 422 etc.
        throw normalizeError(error, integrationId);
      }

      if (attempt < retryConfig.maxAttempts - 1) {
        // Check for Retry-After header (common in 429 responses)
        const retryAfter = error?.response?.headers?.['retry-after'];
        const delay = retryAfter
          ? parseInt(retryAfter, 10) * 1000
          : backoffDelay(attempt, retryConfig);

        console.warn(
          `[${integrationId}] Request failed with ${status}, attempt ${attempt + 1}/${retryConfig.maxAttempts}, retrying in ${delay}ms`
        );
        await new Promise((resolve) => setTimeout(resolve, delay));
      }
    }
  }

  throw normalizeError(lastError, integrationId);
}

Two details here that most implementations skip:

1. Jitter on backoff — without jitter, all clients retry at the same interval after a rate limit hit, causing a thundering herd that immediately triggers the same limit again.
2. Retry-After header respect — Stripe, GitHub, and many others return Retry-After on 429 responses. Ignoring it means your backoff is often either too aggressive or too conservative.

Normalize Errors Across Providers

Your application code should catch a single error type from all integrations, not provider-specific errors:

// integration-error.ts
export type IntegrationErrorCode =
  | 'AUTHENTICATION_FAILED'
  | 'AUTHORIZATION_DENIED'
  | 'RATE_LIMITED'
  | 'NOT_FOUND'
  | 'VALIDATION_ERROR'
  | 'UPSTREAM_UNAVAILABLE'
  | 'TIMEOUT'
  | 'UNKNOWN';

export class IntegrationError extends Error {
  constructor(
    public readonly code: IntegrationErrorCode,
    public readonly integrationId: string,
    message: string,
    public readonly httpStatus?: number,
    public readonly upstreamError?: unknown
  ) {
    super(message);
    this.name = 'IntegrationError';
  }

  isRetryable(): boolean {
    return [
      'RATE_LIMITED',
      'UPSTREAM_UNAVAILABLE',
      'TIMEOUT',
    ].includes(this.code);
  }

  toLogContext(): Record<string, unknown> {
    return {
      errorCode: this.code,
      integrationId: this.integrationId,
      httpStatus: this.httpStatus,
      message: this.message,
      // Never include upstreamError directly — it may contain sensitive data
    };
  }
}

export function normalizeError(error: unknown, integrationId: string): IntegrationError {
  if (error instanceof IntegrationError) return error;

  const axiosError = error as any;
  const status = axiosError?.response?.status;

  const codeMap: Record<number, IntegrationErrorCode> = {
    400: 'VALIDATION_ERROR',
    401: 'AUTHENTICATION_FAILED',
    403: 'AUTHORIZATION_DENIED',
    404: 'NOT_FOUND',
    429: 'RATE_LIMITED',
    500: 'UPSTREAM_UNAVAILABLE',
    502: 'UPSTREAM_UNAVAILABLE',
    503: 'UPSTREAM_UNAVAILABLE',
    504: 'UPSTREAM_UNAVAILABLE',
  };

  const code: IntegrationErrorCode = codeMap[status] ?? 'UNKNOWN';
  const message = axiosError?.response?.data?.message
    ?? axiosError?.response?.data?.error
    ?? axiosError?.message
    ?? 'Unknown integration error';

  return new IntegrationError(code, integrationId, message, status, error);
}

With this pattern, your application code can do:

try {
  await payments.createCustomer(data);
} catch (error) {
  if (error instanceof IntegrationError) {
    if (error.code === 'RATE_LIMITED') {
      // Schedule for later
    } else if (error.code === 'AUTHENTICATION_FAILED') {
      // Alert on-call immediately
    } else if (error.code === 'VALIDATION_ERROR') {
      // Return 400 to the caller
    }
  }
}

No provider-specific logic leaking into business code.

Model Adapters: Normalize Response Shapes

Different APIs return the same logical entity in completely different shapes. A "contact" in Salesforce, HubSpot, and Pipedrive looks nothing alike. A "message" in Twilio versus Mailgun versus Postmark differs significantly.

Build per-provider adapters that translate upstream responses to your internal domain model:

// Domain model
export interface Contact {
  id: string;
  email: string;
  firstName: string;
  lastName: string;
  phone?: string;
  createdAt: Date;
  source: string;
}

// Salesforce adapter
export function fromSalesforceContact(raw: any): Contact {
  return {
    id: raw.Id,
    email: raw.Email,
    firstName: raw.FirstName ?? '',
    lastName: raw.LastName ?? '',
    phone: raw.Phone ?? undefined,
    createdAt: new Date(raw.CreatedDate),
    source: 'salesforce',
  };
}

// HubSpot adapter
export function fromHubSpotContact(raw: any): Contact {
  const props = raw.properties;
  return {
    id: String(raw.id),
    email: props.email,
    firstName: props.firstname ?? '',
    lastName: props.lastname ?? '',
    phone: props.phone ?? undefined,
    createdAt: new Date(raw.createdAt),
    source: 'hubspot',
  };
}

The benefit becomes obvious when you switch CRM providers or run multiple CRMs simultaneously: your application code never changes.

API Versioning Strategy

Pinning API versions is one of the most important production habits teams skip. Here is a practical approach:

1. Pin versions explicitly in configuration:

export const API_VERSIONS = {
  stripe: '2024-12-18.acacia',
  github: '2022-11-28',
  salesforce: 'v59.0',
  hubspot: 'v3',
} as const;

2. Pass version headers consistently:

For Stripe:

axios.defaults.headers['Stripe-Version'] = API_VERSIONS.stripe;

For GitHub:

axios.defaults.headers['X-GitHub-Api-Version'] = API_VERSIONS.github;

3. Track provider changelogs in your dependency review process. Subscribe to provider changelogs and release announcements. Treat API version upgrades the same way you treat npm package upgrades — scheduled, tested, and deployed deliberately.

4. Never use a 'latest' alias in production. The convenience is not worth the risk of a silent breaking change.

5. Test version upgrades in a staging environment using contract tests that verify your adapters against the new response shapes before promoting to production.

Rate Limit Management at the Hub Level

For high-throughput integrations, you need a rate limiter that operates at the hub level, not per-request:

// token-bucket-rate-limiter.ts
export class TokenBucketRateLimiter {
  private tokens: number;
  private lastRefill: number;

  constructor(
    private readonly capacity: number,
    private readonly refillRate: number, // tokens per second
  ) {
    this.tokens = capacity;
    this.lastRefill = Date.now();
  }

  async acquire(tokens = 1): Promise<void> {
    this.refill();
    if (this.tokens >= tokens) {
      this.tokens -= tokens;
      return;
    }
    // Wait until enough tokens are available
    const waitMs = ((tokens - this.tokens) / this.refillRate) * 1000;
    await new Promise((resolve) => setTimeout(resolve, waitMs));
    this.tokens = 0;
  }

  private refill(): void {
    const now = Date.now();
    const elapsed = (now - this.lastRefill) / 1000;
    this.tokens = Math.min(this.capacity, this.tokens + elapsed * this.refillRate);
    this.lastRefill = now;
  }
}

// Usage per integration
const githubLimiter = new TokenBucketRateLimiter(5000, 1.38); // 5000/hour = ~1.38/sec
const stripeLimiter = new TokenBucketRateLimiter(100, 100);   // 100 RPS

Production note: For multi-instance deployments, an in-process token bucket is insufficient because each instance has its own counter. Use a Redis-backed rate limiter (the rate-limiter-flexible library is excellent for this) with shared state across all instances.

Monitoring API Health Across Many Providers

With twenty integrations, you need to know about provider-side outages before your users do. A three-layer monitoring approach works well:

Layer 1: Passive Monitoring from Real Traffic

Instrument your integration hub to emit metrics on every outbound API call:

interface ApiCallMetric {
  integrationId: string;
  endpoint: string;
  statusCode: number;
  durationMs: number;
  attempt: number;
  error?: string;
}

async function trackApiCall(
  fn: () => Promise<AxiosResponse>,
  integrationId: string,
  endpoint: string
): Promise<AxiosResponse> {
  const start = Date.now();
  try {
    const response = await fn();
    emitMetric({
      integrationId,
      endpoint,
      statusCode: response.status,
      durationMs: Date.now() - start,
      attempt: 1,
    });
    return response;
  } catch (error: any) {
    emitMetric({
      integrationId,
      endpoint,
      statusCode: error?.response?.status ?? 0,
      durationMs: Date.now() - start,
      attempt: 1,
      error: error?.code ?? 'UNKNOWN',
    });
    throw error;
  }
}

Forward these metrics to Datadog, Prometheus, or CloudWatch. Build dashboards with:

• Per-provider error rate (5xx, 429 separately)
• P50/P95/P99 latency per provider
• Retry rate (attempts > 1)
• Authentication failure rate

Layer 2: Active Synthetic Checks

Run lightweight read-only requests to each provider on a schedule (every 60 seconds) to detect outages before real traffic hits:

// health-check.ts
export async function checkStripeHealth(): Promise<HealthCheckResult> {
  try {
    const start = Date.now();
    // Stripe's /v1/balance is a safe, lightweight endpoint
    await stripeClient.balance.retrieve();
    return { provider: 'stripe', healthy: true, latencyMs: Date.now() - start };
  } catch (error: any) {
    return {
      provider: 'stripe',
      healthy: false,
      error: error.message,
      latencyMs: 0,
    };
  }
}

Layer 3: Provider Status Page Polling

Many providers expose machine-readable status pages (Atlassian's Statuspage is common). Poll these and correlate with your own error rates:

# Stripe: https://status.stripe.com/api/v2/status.json
# GitHub: https://www.githubstatus.com/api/v2/status.json
# Twilio: https://status.twilio.com/api/v2/status.json

When a provider's status page shows an incident AND your error rate for that provider spikes, you have strong signal for an upstream problem versus a bug in your integration. This distinction is critical for on-call triage.

API Integration Testing Strategy

Testing integrations at scale requires a layered strategy:

Unit tests with recorded fixtures — Record real API responses using tools like nock (Node.js) or VCR (Ruby/Python), then replay them in tests. This gives you fast, deterministic tests that validate your adapter logic without hitting real APIs.

Contract tests — Validate that your adapter expectations match the actual API shape. Run these against real (sandbox) APIs in CI on a nightly basis:

// stripe-contract.test.ts
describe('Stripe Customer Adapter', () => {
  it('fromStripeCustomer maps all required fields', async () => {
    // This runs against Stripe test mode, not a mock
    const raw = await stripe.customers.create({
      email: 'test@example.com',
      name: 'Test User',
    });
    const customer = fromStripeCustomer(raw);

    expect(customer.id).toBe(raw.id);
    expect(customer.email).toBe('test@example.com');
    expect(customer.createdAt).toBeInstanceOf(Date);
  });
});

End-to-end tests in staging — Run critical integration paths (payment creation, notification delivery) against staging environments weekly.

Security Considerations for Integration Hubs

A centralized integration hub is also a centralized attack surface. The security practices that matter most:

Credential isolation: Each integration should have its own credential with the minimum required permissions. Do not share a single API key across multiple integration purposes. Stripe supports restricted keys; GitHub Apps scope permissions per repository; AWS IAM allows per-integration policies.

Outbound request validation: If your hub accepts dynamic parameters that influence API calls (user-supplied filter values, IDs, etc.), validate them before they reach the HTTP layer. Server-side request forgery (SSRF) through integration hubs is a real attack vector.

Audit logging: Log every credential access and every outbound API call with enough context to reconstruct what happened — timestamp, integrationId, endpoint, status code, and the identity of the internal service that triggered the call. Never log request bodies unless they are scrubbed of sensitive fields.

Dependency security: Integration SDKs (the Stripe Node library, the AWS SDK, etc.) are dependencies with their own vulnerability histories. Include them in your dependency scanning pipeline.

For MCP servers that expose integrations to AI agents, the security surface expands further — see the MCP Security Best Practices guide for a full treatment.

Preparing Integrations for AI Agents with MCP

This is where integration architecture is actively changing in 2025. Teams that have already centralized their API integrations have a significant advantage when it comes to exposing those integrations to AI assistants.

The Model Context Protocol (MCP) is an open standard, developed by Anthropic, that defines how AI clients (Claude, Cursor, Windsurf, and others) discover and call external tools. An MCP server is essentially an integration hub with a structured tool interface on top of it.

Instead of building bespoke AI features that each embed their own API glue code, you build one MCP server that wraps your integration hub, and every AI client can use it.

Why This Matters for Multi-API Teams

Without MCP, every AI feature needs its own integration code:

• A Claude-powered support agent needs to call Salesforce, Zendesk, and Stripe separately
• A Cursor coding assistant needs to call GitHub and Linear separately
• Each of these features duplicates authentication, retry logic, and error handling

With MCP, you expose your integration hub as tools once. Every AI client that supports MCP gets all of them.

Structuring Multi-API Tools in an MCP Server

Here is a practical example of an MCP server that wraps multiple integrations:

// multi-api-mcp-server.ts
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { z } from 'zod';
import { paymentsIntegration } from './integrations/payments';
import { crmIntegration } from './integrations/crm';
import { notificationsIntegration } from './integrations/notifications';

const server = new McpServer({
  name: 'company-integrations',
  version: '1.0.0',
});

// Payments tool (wraps Stripe)
server.tool(
  'get_customer_payment_status',
  'Retrieve the payment and subscription status for a customer by email',
  {
    email: z.string().email().describe('Customer email address'),
  },
  async ({ email }) => {
    try {
      const customer = await paymentsIntegration.getCustomerByEmail(email);
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              customerId: customer.id,
              subscriptionStatus: customer.subscriptionStatus,
              currentPlan: customer.currentPlan,
              nextBillingDate: customer.nextBillingDate,
            }),
          },
        ],
      };
    } catch (error) {
      if (error instanceof IntegrationError) {
        return {
          content: [{ type: 'text', text: `Error: ${error.message}` }],
          isError: true,
        };
      }
      throw error;
    }
  }
);

// CRM tool (wraps Salesforce or HubSpot)
server.tool(
  'get_contact_details',
  'Retrieve contact information and account history from CRM',
  {
    email: z.string().email().describe('Contact email address'),
  },
  async ({ email }) => {
    const contact = await crmIntegration.getContactByEmail(email);
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(contact),
        },
      ],
    };
  }
);

// Notifications tool (wraps Twilio/Sendgrid)
server.tool(
  'send_customer_notification',
  'Send an email or SMS notification to a customer',
  {
    email: z.string().email(),
    channel: z.enum(['email', 'sms']).describe('Delivery channel'),
    message: z.string().max(500).describe('Notification message content'),
  },
  async ({ email, channel, message }) => {
    const result = await notificationsIntegration.send({ email, channel, message });
    return {
      content: [
        {
          type: 'text',
          text: `Notification sent. Message ID: ${result.messageId}`,
        },
      ],
    };
  }
);

// Start server
const transport = new StdioServerTransport();
await server.connect(transport);

A few important design decisions in this example:

• Each tool calls your integration hub, not the provider's API directly. The MCP layer does not need to know about Stripe's API shape.
• Errors are normalized before being returned to the AI client, using the same IntegrationError type from earlier.
• Tool descriptions are precise — "Retrieve contact information and account history from CRM" tells the AI client exactly when to use this tool and what it returns.
• Input schemas are strict — .email() validation, .max(500) for message content, .enum(['email', 'sms']) for channel. The AI client cannot pass malformed input.

Authentication for MCP Servers Exposing Real APIs

When your MCP server wraps APIs with real effects (sending notifications, creating payments), authentication at the MCP level is critical. The MCP spec supports OAuth 2.0 for server authentication. For internal tools, Bearer token authentication with short-lived tokens is common.

Never deploy an MCP server that wraps write operations without authentication. An unauthenticated tool that can send emails or charge customers is a critical vulnerability.

Refer to running MCP in production for deployment architecture, process management, and operational considerations.

Verifying MCP Servers Before Connecting

Before connecting any third-party MCP server to your AI client — or before deploying your own MCP server and asking teammates to connect to it — verify it does not expose unexpected tools or exfiltrate data through tool responses.

MCPForge's verification tool scans MCP servers and validates their tool schemas, authentication requirements, and response behaviors. The MCPForge verified directory lists MCP servers that have passed this verification process, which is useful when evaluating third-party integrations for your team's AI clients.

If you are managing security for a larger organization, MCPForge security reports provide structured vulnerability reports for MCP servers in your environment.

Architecture Decision: Shared Library vs. Dedicated Service

For most early-to-mid stage SaaS companies, a well-organized shared library with a clear internal API boundary is the right call. Build the dedicated service when you have multiple teams deploying services that all need the same integrations, and you want a single deployment artifact.

A Practical Integration Checklist

Use this when adding a new third-party API integration:

Authentication

• Credentials stored in secrets manager (not environment variables or code)
• Minimum required permissions scoped on the API key or OAuth app
• Token refresh logic implemented if OAuth 2.0
• Credential caching with TTL shorter than token lifetime

Transport

• API version pinned explicitly in configuration
• Retry logic with exponential backoff and jitter
• Retry-After header respected on 429 responses
• Non-retryable status codes (4xx) fail immediately
• Request timeout configured (not left at library default)

Error handling

• Provider errors normalized to IntegrationError
• Sensitive fields not included in error logs
• Error codes mapped to application-level actions

Data modeling

• Response adapter function maps to internal domain model
• Adapter has unit tests with recorded fixtures
• Contract test validates adapter against live sandbox API

Monitoring

• Metrics emitted on every API call (status, latency, integration ID)
• Active health check endpoint registered
• Alert configured for sustained error rate above threshold
• Provider status page URL documented

Security

• Outbound request parameters validated before use
• Audit log entry on every credential access
• Integration added to dependency scanning

Common Mistakes and How to Avoid Them

Catching and swallowing errors silently — The most common integration bug. A request fails, the catch block logs nothing meaningful, and the application continues as if it succeeded. Always either re-throw (with normalization) or return a typed error result.

Sharing a single API key across multiple services — When that key is compromised or rate-limited, every service fails simultaneously. Use separate credentials per service or environment.

Not testing what happens when a provider is down — Most integration code is never tested for the case where the provider returns 503 for five minutes. Add chaos tests that inject failures and verify your circuit breaker and retry logic behave as expected.

Building fan-out calls without concurrency limits — If your integration hub receives a request that triggers calls to five providers simultaneously, and all five are slow, your request timeout is determined by the slowest provider. Use Promise.allSettled instead of Promise.all for non-critical fan-out, and cap concurrent outbound requests.

Forgetting that sandbox and production API behaviors differ — Some providers return different error shapes, different rate limits, or different response fields between sandbox and production. Test in production with low-risk operations, not only in sandbox.

No process for tracking upstream API changes — Set up GitHub watching or RSS subscriptions for provider changelogs and release notes. Assign someone on the team to review these weekly. Breaking changes caught early cost 10% of what they cost in production.

Key Takeaways

Managing multiple API integrations efficiently comes down to applying engineering discipline consistently rather than heroics:

1. Centralize before you duplicate - Every integration should go through a shared hub. The first time you build an integration directly in application code, you are writing tech debt.

2. Authenticate from a vault, not from env vars - Credential sprawl is a security and reliability problem that compounds with every integration you add.

3. Retry logic and error normalization belong in the transport layer - Not in application code. Not reimplemented per integration.

4. Pin API versions and track changelogs - Silent breaking changes from a provider update are preventable. The process costs less than the incident.

5. Monitor at three levels - Passive (real traffic metrics), active (synthetic health checks), and external (provider status pages).

6. Your integration hub is your MCP server - If you have centralized your integrations well, exposing them to AI agents is a thin layer on top of what you have already built. The teams that do this first gain significant productivity advantages from AI tooling.

The investment in a proper integration architecture pays compounding returns. Every new integration is cheaper to build, every incident is faster to triage, and every AI feature is faster to ship.