API Integration Best Practices: Lessons from 50+ Projects
Common pitfalls and proven patterns for building reliable third-party integrations that scale.
The Hidden Complexity of API Integrations
"Just connect to their API" sounds simple—until you're debugging rate limits at 2 AM or handling webhook retries for the hundredth time.
After building 50+ integrations (Stripe, Shopify, HubSpot, Salesforce, and more), here are the patterns that actually work.
The Five Pillars of Reliable Integrations
1. Never Trust External Data
Always validate and sanitize data from third-party APIs:
// Bad: Trusting external data
const price = response.data.price;
// Good: Validate and provide fallbacks
const price = Number(response.data?.price) || 0;
if (price < 0 || price > 1000000) {
throw new ValidationError('Invalid price received');
}
2. Implement Exponential Backoff
When APIs fail (and they will), retry intelligently:
- First retry: 1 second
- Second retry: 2 seconds
- Third retry: 4 seconds
- Max retries: 3-5 attempts
3. Use Webhook Idempotency
Webhooks can fire multiple times. Always:
- Store webhook IDs
- Check for duplicates before processing
- Use database transactions
4. Monitor Everything
Track these metrics for every integration:
- Response times (p50, p95, p99)
- Error rates by type
- Rate limit usage
- Data freshness
5. Plan for Deprecation
APIs change. Build abstractions:
- Wrap third-party SDKs in your own service layer
- Version your integration code
- Subscribe to API changelogs
Real-World Example: HubSpot + Salesforce Sync
For a London-based client, we built a bi-directional sync that:
- Eliminated 80% of manual data entry
- Saved 15 hours/week in admin time
- Reduced sync errors from 20/month to near-zero
The key? Conflict resolution rules defined upfront and a "source of truth" hierarchy.
Need Integration Help?
From payment gateways to CRM connections, we've got you covered.