Retry Failed PHP cURL Requests Without Repeating Permanent Errors
A retry loop gives a PHP script another chance after a brief outage, rate limit or connection hiccup, instead of ending on the first failure.
The pattern below is designed for temporary problems only: it stops immediately on success, stops immediately on a permanent client error, waits longer after each failed attempt, and gives up after a fixed limit.
Build the loop
Create a file named retry.php, insert the complete example from protected module code0001, and replace the placeholder key with the configured value before running it. The example sets a maximum of five attempts, a 10-second connection timeout and a 30-second overall request timeout. It builds the request URL from parameters, initializes cURL once, and reuses that handle inside the loop.
Separate transport failures from HTTP failures
Each iteration calls curl_exec(). If that returns false, the failure happened before an HTTP response was available, so the script prints the cURL error and continues to the next attempt. If a response arrives, the script reads its status with curl_getinfo(). Any 2xx result is treated as success: the body is printed and the loop breaks. A status outside the retryable list also breaks the loop, because repeating it would not fix the request.
Retry only temporary HTTP failures, with growing delays
Retry only these codes in the example: 429 Too Many Requests, 500 Internal Server Error, 502 Bad Gateway, 503 Service Unavailable and 504 Gateway Timeout. After a retryable failure, the delay doubles each time, producing waits of 1, 2, 4 and 8 seconds before the remaining attempts. When the fifth attempt fails, the script reports that the maximum retry limit has been reached and closes the handle.
Decision checklist: retry or fix first?
Use the decision table below before adding a code to the retryable list. If fixing the request could change the result, return the error instead of retrying it. If waiting could change the result, retry with backoff and a hard attempt limit.
Test the failure path
To force repeated failure, change the URL assignment before cURL is initialized. Replace the assignment in protected module code0002 with the always-failing endpoint in protected module code0003, then run the script with protected module code0004. Reassigning the URL after curl_init() has already read it will not change the request. The expected terminal output is captured in image0003: five attempts against HTTP 503, with increasing delays, followed by the maximum-limit message.
Test the success path
For the success path, replace the failing URL with the endpoint in protected module code0005 and run the script again using protected module code0006. The loop should end on the first attempt, as shown in image0004, because a 200 response falls inside the 2xx success range.
Troubleshoot the common failures
If curl_init() is undefined, the PHP cURL extension is missing or disabled. Enable it for your operating system and verify with protected module code0007; the expected module list is shown in image0005. If a successful request keeps being retried, check that the status code is read after curl_exec() and that the 2xx break from protected module code0008 is present. If client errors such as 400, 401, 403 or 404 are being retried, remove them from the retryable list unless the API documentation describes them as temporary. If the whole script takes too long, reduce the timeout, attempt limit or backoff delays.
Summary
A sound retry policy has three parts: retry only failures that may clear with time, wait progressively longer between attempts, and stop after a defined limit. Permanent client errors should surface immediately so the request can be corrected. That combination recovers from brief connection problems, rate limits and server failures without hiding bugs or wasting time on requests that will fail the same way every time.
| Situation | Example codes or signals | Action |
|---|---|---|
| Connection never completed | curl_exec() returns false; empty reply or 000 status | Retry, up to the attempt limit |
| Rate limited or server temporarily unavailable | 429, 500, 502, 503, 504 | Retry with increasing delay |
| Request needs correction | 400, 401, 403, 404 | Stop and fix the request first |
| Request succeeded | 200-299 | Print the response and stop |
The retryable list is the example's policy, not a universal rule. Follow the target API's documentation when it classifies an error as temporary.
Frequently asked questions
Why check both curl_exec() and the HTTP status code?
A cURL-level failure makes curl_exec() return false, for example when the connection fails. An HTTP error such as 404 or 503 is different: curl_exec() can still return a body, so the script must inspect the status code separately with curl_getinfo().
Which status codes should be retried?
429, 500, 502, 503 and 504 are treated as retryable in the example. Codes such as 400, 401, 403 and 404 normally need the request changed first, so they should not be repeated unless the API documentation says the error is temporary.
How long does the example wait between attempts?
The example allows up to five attempts and waits 1, 2, 4 and 8 seconds between retries. If the total time is too long, lower the request timeout, the retry limit, or the delay between attempts.
What does an empty reply or 000 status mean?
An empty reply, shown as curl: (52) Empty reply from server or a 000 status, means the connection did not complete. That usually points to a network or firewall problem rather than the endpoint itself, so test the URL directly with the supplied curl command in code0009.
What if curl_init() is undefined?
Install or enable the PHP cURL extension for your operating system, then run the module check in code0007 and confirm that curl appears in the output.
curl -i https://postman-echo.com/status/200