Skip to main content

Validate and Retry requests

Overview​

Server API requests can fail even when they are correctly sent. Temporary issues like traffic spikes, brief outages, network problems, or slow upstream services can prevent a successful response. These errors are usually short-lived and often resolve on their own.

Failing immediately on such errors reduces reliability, while retrying too often can overload the server. Exponential retries solve this by spacing out retry attempts, increasing the delay each time. This gives the server time to recover and improves the chances of success, leading to more stable and reliable integrations.

How to Implement Exponential Retry​

This section defines the expected client behavior for implementing an exponential retry mechanism.

Step 1: Send the Request Normally​

  • Execute the API request once
  • Do not apply any delay on the initial attempt

Step 2: Evaluate the Failure Type​

If the request fails, the client must determine:

  • Was an HTTP response received?
  • If yes, what is the HTTP status code?
  • If no, did a network or transport error occur?

This classification determines whether a retry is allowed.

Step 3: Decide Whether the Error Is Retryable​

Only retry if all of the following are true:

  • The failure is considered transient
  • Retrying the same request later may succeed
  • The request is safe to retry (idempotent or protected)

If any of these conditions is false, the request must fail without attempting any retry policy.

Step 4: Apply Exponential Backoff Before Retrying​

When a retry is allowed:

  • Wait before retrying
  • Increase the waiting time exponentially for each attempt

The delay must:

  • Start small (eg: 500ms)
  • Increase progressively (eg: duplicate in each request)
  • Be capped to a reasonable maximum (eg: maximum of 10 minutes)

Example Timeline​

AttemptDelay
1500 ms
21 s
32 s
44 s
58 s

Step 5: Limit Retries​

The retry policy should have a limit defined to avoid infinite requests, thus overloading the server API. Once the limit is reached:

  • Stop retrying
  • Surface the error to the caller

Error Codes and Retry Policy​

This section defines when exponential retry should or should not be triggered based on the error type of the HTTP Request.

CategoryRetry with Exponential Backoff
Network errors✅ Yes
408 Request Timeout✅ Yes
429 Too Many Requests✅ Yes
460 Client Timeout✅ Yes
5xx Server Errors✅ Yes
1xx Informational Responses❌ No
2xx Successful responses❌ No
4xx Client Errors (400, 401, 403, 404, 409, 422)❌ No

Other undefined error types should be individually identified in order to improve the success rate of the requests made.


Final Notes for API Consumers​

  • Retry logic must be deterministic and bounded
  • Server-provided retry hints always take precedence
  • Incorrect retries can be more harmful than no retries

Following these rules ensures predictable, safe, and scalable integrations with Server APIs.