5 common mistakes in 3rd party API integrations

Every significant project involves a 3rd party API integration. Payment service, shipping tracking, SMS gateway, maps API... And nearly every project repeats the same mistakes.

1. Ignoring idempotency

Webhooks and async API calls can arrive more than once. Processing an order twice or charging a customer twice is catastrophic.

Use a unique idempotency-key for every critical operation:

await stripe.paymentIntents.create({
  amount,
  currency: "usd",
  idempotencyKey: `order_${orderId}`,
});

2. Showing raw API errors to users

"upstream connect error or disconnect/reset before headers" should never reach the end user. Catch errors, translate them into meaningful messages, and log the details internally.

try {
  await externalApi.call();
} catch (err) {
  logger.error("external_api.failed", { err });
  throw new UserFacingError("This action cannot be completed right now.");
}

3. Not planning for rate limits

Third-party APIs have rate limits. Firing 100 requests per second at a shipping API is prohibited. Caching and request queuing should be planned from day one.

4. Using the same credentials for test and production

Put sandbox keys in .env.local. Use mocks in CI. Production keys should never leave the production environment.

5. Not verifying webhook signatures

You're creating a public endpoint; anyone can POST to it. Always verify the signature:

const isValid = stripe.webhooks.constructEvent(
  rawBody,
  signature,
  process.env.STRIPE_WEBHOOK_SECRET!,
);

---

Want to set up a secure integration architecture? Let's talk.