API integrations are the connective tissue of modern web and app development. They are also the source of some of the most expensive, hard-to-debug production failures. These are the integration mistakes that break systems at the worst possible times.
Modern web and mobile applications are built on integrations. Payment processors, mapping services, CRM systems, authentication providers, shipping APIs, marketing platforms — the average business application integrates 10 to 15 external APIs. Each integration is a potential point of failure, a security risk, and a source of technical debt if not handled correctly.
At App Basis Inc, we have inherited many projects where API integration failures were the root cause of significant production problems. The same mistakes appear repeatedly. Here is how to avoid them.
Mistake 1: No Rate Limit Handling
Every external API imposes rate limits. Exceed them and the API returns 429 (Too Many Requests) errors. Applications that do not handle rate limits either crash, produce errors for users, or infinitely hammer the API until they are banned. This is a surprisingly common oversight, especially in applications with batch processing or high user concurrency.
Fix: Implement exponential backoff with jitter for all API calls. On receiving a 429 response, wait before retrying — and double the wait time with each successive failure. Respect the Retry-After header when provided. Implement request queuing for batch operations to distribute API calls over time.
Mistake 2: API Credentials in Version Control
API keys, client secrets, webhook signing secrets, and database credentials committed to a Git repository — even a private one — are a critical security vulnerability. Repository access can be compromised. Private repositories can accidentally become public. GitHub's secret scanning tools detect exposed credentials and notify the API provider, who may disable the key before you even know there was a breach.
Fix: Never commit credentials to version control. Use environment variables exclusively. Store environment variables in a secure secrets manager: AWS Secrets Manager, HashiCorp Vault, Doppler, or a platform-native secrets service. Add a .gitignore entry for all .env files. Rotate any credentials that have ever been committed, even briefly.
Mistake 3: No Timeout Configuration
By default, many HTTP clients have no timeout — they wait indefinitely for a response. A slow or hung external API can cause your application's request threads to pile up waiting for a response that never comes, eventually exhausting your server's connection pool and taking down the entire application.
Fix: Configure explicit timeouts for every external API call: a connection timeout (time to establish the connection) and a read timeout (time to receive the complete response). Reasonable values depend on the API — most should respond within 5 to 10 seconds. For long-running operations, use the API's async pattern (submit a job, poll for completion) rather than holding a synchronous connection open.
Mistake 4: Not Validating API Responses
Assuming an API response always returns the expected schema is a recipe for null pointer exceptions, type errors, and data corruption. APIs change. They return partial data under load. They return unexpected error formats when services degrade. Applications that do not validate response structure before consuming it fail in unpredictable and hard-to-debug ways.
Fix: Validate API responses against a schema before processing. Define TypeScript interfaces or Zod schemas for every API response type. Check for expected fields before accessing them. Handle missing or null values explicitly. Monitor for unexpected response shape changes with API contract testing tools like Pact or Dredd.
Mistake 5: Synchronous API Calls in Request/Response Cycle for Long Operations
Calling a slow API (image processing, report generation, email sending) synchronously within a user-facing HTTP request causes the user to wait for the API to complete. If the API takes 10 seconds, the user waits 10 seconds. If the API fails, the user request fails. This pattern creates brittle, slow user experiences and server timeouts under load.
Fix: Move time-consuming external API calls to background job queues. Accept the user's request, queue the operation, and return immediately with a job ID or status URL. Poll for completion or use webhooks to notify users when the operation finishes. Laravel Queues, Celery, Sidekiq, and BullMQ are common solutions.
Mistake 6: Not Handling Webhooks Securely
Webhooks — inbound API callbacks from external services — are frequently implemented without signature verification. Without verification, any attacker who discovers your webhook URL can send fraudulent events: fake payment confirmations, fake order completions, or fake user creation events that trigger business logic in your application.
Fix: Always verify webhook signatures using the signing secret provided by the service. Stripe, GitHub, Twilio, and most modern API providers include a signature in webhook headers (e.g., Stripe-Signature). Validate the signature against the raw request body before processing any webhook event. Return 200 immediately to acknowledge receipt, then process asynchronously.
Mistake 7: No Circuit Breaker Pattern
When an external API is degraded or down, applications without circuit breakers continue making failing requests — accumulating timeout penalties, exhausting connection pools, and cascading failures to dependent services. The application effectively amplifies the external API's outage into a complete internal system failure.
Fix: Implement the circuit breaker pattern for all external API integrations. After a configurable number of consecutive failures, the circuit breaker opens — subsequent calls fail immediately without attempting the network request. After a timeout period, the circuit moves to half-open and allows a test request through. If it succeeds, the circuit closes and normal operation resumes. Libraries: Resilience4j (Java), Polly (.NET), opossum (Node.js).
Building Resilient API Integrations
The best API integration fails gracefully, respects the external service's constraints, and degrades functionality rather than crashing when dependencies are unavailable. Building this resilience from the start requires more upfront engineering effort — but it eliminates the 3am production fires that plagued teams who did not build it in.
App Basis Inc designs and implements API integrations for web and mobile applications serving DFW businesses. Contact us to discuss your integration architecture.