API Integration Patterns Every Forward Deployed Engineer Uses
The Job Nobody Prepares You For
Nobody tells you what the first week as a Forward Deployed Engineer actually looks like. You are sitting inside a customer's engineering office, their integration is broken, their CTO is in the room, and you have four hours to fix something you have never seen before using an API you shipped but never had to consume yourself.
This is the core FDE challenge: you understand the product deeply but the customer's codebase is a black box. Their architecture decisions, their tech stack, their error handling patterns — all unknown. The only constant is the API surface. Every integration problem you will ever solve as an FDE runs through an API, and knowing the patterns cold is what separates engineers who fix things fast from engineers who look lost under pressure.
This post covers the API integration patterns you will encounter repeatedly in the field — how to recognise them, how to implement them correctly, and where each one breaks.
🎯 Quick Answer (30-Second Read)
- Most common FDE integration patterns: Webhooks, polling, pagination, auth flows, rate limit handling, idempotency, and error retry logic
- Most common failure mode: Customers implement the happy path and skip error handling entirely
- Most valuable FDE skill: Reading an integration and knowing immediately which pattern is missing
- Tool you will use most: A good HTTP client and logging — Postman, curl, and structured logs catch 80% of integration bugs
- Core principle: An integration that works in development and breaks in production is missing one of the patterns in this post
Pattern 1 — Webhook Receiver (The One Customers Always Get Wrong)
Webhooks are the first pattern you will debug in the field. A customer says "we are not receiving events" and nine times out of ten the webhook receiver has one of three problems: it is not returning 200 fast enough, it is not verifying the signature, or it is processing synchronously and timing out.
The correct webhook receiver pattern:
app.post('/webhook', async (req, res) => {
// 1. Verify signature immediately
const signature = req.headers['x-webhook-signature'];
if (!verifySignature(req.body, signature, process.env.WEBHOOK_SECRET)) {
return res.status(401).json({ error: 'Invalid signature' });
}
// 2. Acknowledge immediately — before any processing
res.status(200).json({ received: true });
// 3. Process asynchronously after response is sent
await queue.add('process-webhook', req.body);
});Why customers get this wrong: They put database writes and downstream API calls between receiving the webhook and sending the 200. If that processing takes more than 5–30 seconds (depending on the provider), the webhook provider retries — which creates duplicate events. The customer sees the same order processed twice and thinks your API has a bug.
What you do as an FDE: Acknowledge first, process after. Always. Show them the queue pattern and explain why the 200 must go out before any business logic runs.
Pattern 2 — Polling with Exponential Backoff
When webhooks are not available or the customer cannot expose a public endpoint, they fall back to polling. Polling done wrong hammers your API and burns through rate limits in minutes. Polling done right is efficient and resilient.
async function pollWithBackoff(jobId, options = {}) {
const {
maxAttempts = 10,
baseDelay = 1000,
maxDelay = 30000
} = options;
for (let attempt = 0; attempt < maxAttempts; attempt++) {
const result = await api.getJobStatus(jobId);
if (result.status === 'complete') return result;
if (result.status === 'failed') throw new Error(result.error);
// Exponential backoff with jitter
const delay = Math.min(
baseDelay * Math.pow(2, attempt) + Math.random() * 1000,
maxDelay
);
await sleep(delay);
}
throw new Error('Max polling attempts exceeded');
}The jitter (random component) is critical at scale. Without it, every customer instance that started polling at the same time will retry at the same time — creating a thundering herd that spikes your API load in waves. Jitter spreads the load.
When you see this in the field: A customer complaining that their integration works fine for small jobs but fails for large ones is usually hitting a polling timeout. They poll for 30 seconds, give up, and mark the job as failed — even though the job completes at 45 seconds.
Pattern 3 — Pagination (Cursor vs Offset)
Every FDE will implement pagination for a customer at some point. The customer wants to sync all their data from your API on initial setup or pull a report. Most customers default to offset pagination because it is intuitive. It is also wrong for large datasets.
Offset pagination — breaks at scale:
// Page 1: LIMIT 100 OFFSET 0
// Page 2: LIMIT 100 OFFSET 100
// Problem: if a record is inserted between page 1 and page 2,
// one record gets skipped. At page 500, the database is
// scanning 50,000 rows to skip them. Gets slow fast.Cursor pagination — correct:
async function* paginateAll(endpoint) {
let cursor = null;
do {
const params = cursor ? { cursor, limit: 100 } : { limit: 100 };
const response = await api.get(endpoint, { params });
yield response.data;
cursor = response.next_cursor;
} while (cursor);
}
// Usage — processes all records without loading into memory
for await (const page of paginateAll('/events')) {
await processPage(page);
}What you fix as an FDE: Customers who built offset pagination for their initial data sync and are now hitting timeouts on page 200 because the database scan is taking 8 seconds per page. Show them cursor pagination and the generator pattern so they are not loading 50,000 records into memory at once.
Pattern 4 — Authentication Flows
FDEs handle three auth patterns repeatedly: API keys, OAuth 2.0, and JWT refresh flows. Each has a specific failure mode you will see in the field.
API key pattern — the failure is almost always header naming:
// Wrong — customers guess at the header name
headers: { 'Authorization': apiKey }
// Wrong — missing Bearer prefix
headers: { 'Authorization': `Bearer ${apiKey}` } // for API keys that need Bearer
// Right — check the docs, use exactly the specified header
headers: { 'X-API-Key': apiKey }OAuth 2.0 token refresh — the failure is always missing the refresh logic:
class ApiClient {
async request(endpoint, options) {
try {
return await this.makeRequest(endpoint, options);
} catch (error) {
if (error.status === 401) {
// Token expired — refresh and retry once
await this.refreshAccessToken();
return await this.makeRequest(endpoint, options);
}
throw error;
}
}
async refreshAccessToken() {
const response = await fetch('/oauth/token', {
method: 'POST',
body: new URLSearchParams({
grant_type: 'refresh_token',
refresh_token: this.refreshToken,
client_id: this.clientId,
client_secret: this.clientSecret
})
});
const tokens = await response.json();
this.accessToken = tokens.access_token;
this.refreshToken = tokens.refresh_token;
await this.saveTokens(tokens);
}
}What you fix as an FDE: Customers who are logging out users every hour because they never implemented token refresh. The integration works perfectly for 59 minutes and then silently fails. They blame the API. You add twelve lines of refresh logic and the problem disappears.
Pattern 5 — Rate Limit Handling
Every customer integration will hit rate limits eventually. The ones who handle it correctly have a queue and a retry mechanism. The ones who handle it incorrectly have a while loop that hammers the API until it starts working.
async function requestWithRateLimit(fn, options = {}) {
const { maxRetries = 3 } = options;
for (let attempt = 0; attempt <= maxRetries; attempt++) {
const response = await fn();
if (response.status !== 429) return response;
// Read the retry-after header — always use it if present
const retryAfter = response.headers['retry-after'];
const waitMs = retryAfter
? parseInt(retryAfter) * 1000
: Math.pow(2, attempt) * 1000;
console.log(`Rate limited. Waiting ${waitMs}ms before retry ${attempt + 1}`);
await sleep(waitMs);
}
throw new Error('Rate limit retries exhausted');
}The header most customers miss: Retry-After tells you exactly how long to wait. X-RateLimit-Remaining tells you how many requests you have left in the current window. X-RateLimit-Reset tells you when the window resets. Reading these headers and acting on them is the difference between a resilient integration and one that breaks under load.
Pattern 6 — Idempotency Keys
This is the pattern most customers have never heard of and the one that prevents the most painful production bugs. An idempotency key ensures that retrying a failed request does not create duplicate operations.
const { v4: uuidv4 } = require('uuid');
async function createOrderSafely(orderData) {
// Generate once, store with the order attempt
const idempotencyKey = `order-${orderData.customerId}-${uuidv4()}`;
// If this request fails and is retried with the same key,
// the API returns the original response instead of creating a duplicate
const response = await api.post('/orders', orderData, {
headers: {
'Idempotency-Key': idempotencyKey
}
});
return response;
}When you explain this to a customer: "If your server crashes after we receive the request but before you receive our response, you do not know if the order was created. Without an idempotency key, retrying creates a duplicate order. With an idempotency key, retrying is safe — we return the original result."
The field scenario: A customer's payment integration is creating duplicate charges during network instability. They have no idempotency keys. The fix is adding the header and generating a stable key per payment attempt — not per retry.
Pattern 7 — Structured Error Handling
The integration pattern that separates production-ready code from demo code is how errors are handled. Every API call can fail. How the customer handles that failure determines whether a bug is a 2-minute fix or a 2-hour incident.
class ApiError extends Error {
constructor(status, code, message, details) {
super(message);
this.status = status;
this.code = code;
this.details = details;
}
}
async function apiRequest(endpoint, options) {
const response = await fetch(endpoint, options);
if (!response.ok) {
const error = await response.json();
throw new ApiError(
response.status,
error.code,
error.message,
error.details
);
}
return response.json();
}
// Handle errors by type — not just by status code
try {
await apiRequest('/orders', options);
} catch (error) {
if (error instanceof ApiError) {
switch (error.code) {
case 'INSUFFICIENT_FUNDS':
return notifyCustomer('Payment failed — insufficient funds');
case 'RATE_LIMITED':
return scheduleRetry(error.details.retryAfter);
case 'VALIDATION_ERROR':
return logAndAlert('Invalid request data', error.details);
default:
return escalate(error);
}
}
throw error; // Re-throw non-API errors
}What you find in the field: Customers who catch all errors with a generic console.error and return a 500 to their users. The logs show "API error" with no status code, no error code, no details. You cannot debug what you cannot see. Structured error handling is the first thing you add to any integration you inherit.
My Take
The reason FDEs become invaluable to the companies they work with is not that they know the product better than anyone else — though they do. It is that they have seen every integration fail in every possible way and they pattern-match instantly. When a customer says "events are delayed sometimes", an experienced FDE hears "webhook receiver is processing synchronously." When they say "we get duplicate records during high load", an FDE hears "no idempotency keys." The best outcome of learning these patterns deeply is that you walk into a broken integration, identify the missing piece in ten minutes, and fix it in thirty. The worst outcome is what most junior FDEs experience: spending four hours debugging a customer escalation that is a missing retry-after header read. The industry still treats API integration as a solved problem that any developer can figure out on the fly — which is why so many enterprise integrations are held together with polling loops and silent error swallows. Where this is heading: AI coding tools are generating the happy path faster than ever, which means the gap between "it works in dev" and "it works in production" is growing. The FDE who understands why idempotency, backoff, and structured errors matter will be more valuable in an AI-assisted world, not less — because the AI generates the code and the FDE catches what the AI missed.
Comparison Table
| Pattern | What It Solves | Most Common Mistake |
|---|---|---|
| Webhook Receiver | Real-time event delivery | Processing before acknowledging |
| Polling with Backoff | Async job status | Fixed intervals, no jitter |
| Cursor Pagination | Large dataset sync | Offset pagination at scale |
| OAuth Token Refresh | Auth session management | No refresh logic |
| Rate Limit Handling | API quota management | Ignoring Retry-After header |
| Idempotency Keys | Duplicate prevention | No key on payment/mutation calls |
| Structured Errors | Debuggable integrations | Generic catch-all error handling |
Real Developer Use Case
An FDE was called into a fintech customer who was seeing duplicate transactions during peak load. The integration was creating payment records, calling the payment API, and retrying on timeout — without idempotency keys. Network latency during peak hours was causing the payment API call to time out after the payment had already been processed, triggering a retry that created a second charge.
The fix was three things: add idempotency keys generated per payment attempt, read the Retry-After header instead of using a fixed 1-second retry, and add structured error handling that distinguished timeout errors (retry safe with idempotency key) from validation errors (do not retry). Total code change: under 40 lines. Total time to diagnose and fix: two hours. Duplicate transaction rate: zero after deployment.
Frequently Asked Questions
What is the most common API integration mistake FDEs fix?
Missing error handling on retry logic. Most customers implement the happy path — successful request, process response, move on. They do not handle timeouts, rate limits, or partial failures. When the network has a bad moment or the API has a slow response, the integration fails silently or creates duplicates. Adding structured retry logic with backoff and idempotency keys fixes the majority of production integration incidents.
How do FDEs learn a customer's integration so fast?
Start with the logs and the HTTP traffic. Postman or a network proxy shows you exactly what requests are going out and what responses are coming back. From there, find the integration code — usually one file or one service — and read it top to bottom. Most integrations are small. The pattern you are looking for is which of the seven patterns above is missing.
Should FDEs use SDKs or call APIs directly?
SDKs when they exist and are maintained — they handle auth, retries, and pagination correctly by default. Raw HTTP calls when the SDK is outdated, missing features, or when you need to debug exactly what is happening at the wire level. Always know how to drop down to raw requests — SDKs hide problems that you sometimes need to see.
How do you handle a customer whose integration you cannot fix in the time you have?
Triage first. Identify whether the issue is in the integration code (your domain), the customer's infrastructure (their domain), or a product bug (back to engineering). If it cannot be fixed on-site, document exactly what you found — HTTP logs, error codes, reproduction steps — so engineering can take it without starting from zero. Never leave a customer site without a clear next step and owner.
What is the difference between a webhook and a polling integration?
A webhook is push-based — your server sends an event to the customer's endpoint when something happens. Polling is pull-based — the customer's code asks your API repeatedly whether something has happened. Webhooks are more efficient and real-time but require the customer to have a publicly accessible endpoint. Polling is simpler to implement but burns API quota and introduces latency equal to the polling interval.
Conclusion
These seven patterns cover the majority of API integration work you will do as a Forward Deployed Engineer. Webhooks, polling, pagination, auth, rate limits, idempotency, and error handling are not advanced topics — they are table stakes. The customers who have all seven implemented correctly have integrations that run without incident for years. The ones missing two or three are the ones generating support tickets and escalations.
Learn these patterns until you can identify the missing one in ten minutes of reading unfamiliar code. That speed is what makes an FDE valuable in the field.
Related reads: What Is a Forward Deployed Engineer · How to Structure a Codebase for AI Agents · CI/CD Explained: What It Is and Why Dev Teams Need It