Skip to content

Knowledgebase

Applying HTTP timeouts and limited retries to an API client

development

An outbound API request should have a bounded wait and a retry policy appropriate to the operation. A network timeout does not prove the remote service performed no action.

What you need before you begin

Identify the operation’s side effects, provider retry guidance and supported idempotency mechanism. Set a time budget for the user request or background job.

01 Apply HTTP timeouts and limited retries to an API client

  1. Configure connection and response timeouts in the HTTP client. Keep the overall operation deadline in mind when several attempts are possible.

  2. Classify failures. Temporary network or selected service errors may be retryable, while invalid credentials or request validation errors normally need a correction.

  3. Use limited retries with delay and jitter where appropriate. Respect provider retry instructions and stop when the total time or attempt budget is exhausted.

  4. For state-changing requests, use a provider-supported idempotency key or reconcile status before retrying an uncertain result.

  5. Record safe request identifiers, attempt counts and final outcomes. Move longer recovery work into a queue rather than blocking the browser indefinitely.

02 Example: place limits around a harmless API status check

Start with a read-only endpoint whose retry behaviour is documented. This curl example limits connection time and each attempt, permits at most two retries, and places a window on starting further retries. Replace the URL with the approved status endpoint.

Command example
curl --silent --show-error --fail-with-body \
  --connect-timeout 3 --max-time 10 \
  --retry 2 --retry-max-time 25 \
  'https://api.example.com/v1/status'

The retry window is not a hard deadline for the entire surrounding job: an attempt already started can consume its own timeout. Apply the job’s overall deadline separately. Capture curl’s exit status and a sanitised error summary. Do not reuse this retry policy blindly for a payment, provisioning request or other state-changing operation.

Expected result: A stalled endpoint stops consuming the worker indefinitely. A temporary failure receives only the permitted attempts, and an exhausted job remains visibly failed or deferred for deliberate recovery.

Confirm the expected result

Test a controlled timeout and temporary error in staging. Confirm retries stop and do not produce duplicate external actions or a surge of simultaneous requests.

Troubleshoot unexpected results

If retries worsen an outage, reduce concurrency and respect the provider’s recovery signals. Infinite immediate retries can exhaust both your account and the remote service.

A common question

Should every failed POST request be retried automatically?

No. The original request may already have succeeded remotely. Use the operation’s documented idempotency or status-checking behavior before repeating it.

Was this answer helpful?

Need a little more help?

Our support team can help you find the next step.

Contact support