10 steps before letting an external API into production
1. Read the docs
Auth, base URL, versioning, rate limits, error format. 30 minutes of reading saves days of debugging.
2. Keys and secrets
Keys live only in env/secret store, never in code or frontend. Separate keys for dev/prod.
3. Timeouts and retries
Timeout every request (5–15 s), exponential backoff on 5xx/429, max 3 attempts. A request without timeout hangs your service.
4. Idempotency
A retried request must not create duplicates: use idempotency keys or unique external IDs for writes.
5. Webhooks
Verify webhook signatures, respond 200 fast (process via queue), keep raw payloads for debugging.
6. Error handling
Distinguish client errors (4xx — your fault), server (5xx — theirs), network. Log response bodies on failure.
7. Provider limits
Daily/monthly quotas, per-request cost. Add a circuit-breaker so a stuck loop can't burn the budget.
8. Monitoring
Metrics: request success rate, latency, quota usage. Alert when success drops below threshold.
9. Fallback mode
What does your service do when the API is down? Cache, retry queue, graceful degradation — decide before the incident.
10. Version changes
Subscribe to the provider changelog, pin the API version in config, plan migration before the sunset date.
Common mistakes