No matter how reliable an API is, network failures happen. Building resilient integrations means planning for failure and recovering gracefully. In this guide, we cover three essential patterns for fault-tolerant API integrations.
Exponential Backoff
When a request fails due to a transient error (5xx status codes or network timeouts), retry with exponentially increasing delays. Start with a base delay of 1 second and double it with each attempt: 1s, 2s, 4s, 8s. Add random jitter (±25%) to prevent thundering herd problems when many clients retry simultaneously.
Circuit Breakers
A circuit breaker prevents your application from repeatedly calling a failing service. Track the failure rate over a sliding window. When failures exceed a threshold (e.g., 50% of requests over 30 seconds), open the circuit and immediately return cached data or a graceful fallback. Periodically allow a single test request through to check if the service has recovered.
Idempotency Keys
For write operations, use idempotency keys to ensure that retried requests do not create duplicate resources. Include an Idempotency-Key header with a unique identifier (such as a UUID) for each logical operation. Our API recognizes duplicate requests within a 24-hour window and returns the original response.
Putting It All Together
Our official SDKs implement all three patterns by default. If you are building a custom integration, combine these patterns into a resilient HTTP client wrapper that handles retries, circuit breaking, and idempotency transparently.