Retry Failed Requests in Python
A first request often succeeds, but some calls will fail.
When the API returns a 500 status code, the request is not charged. The pattern below wraps a client call in a fixed retry loop: it stops as soon as the response is OK and saves the screenshot; otherwise it prints the response content and tries again up to the limit.
What the retry loop does
The loop runs at most MAX_RETRIES times. On each pass it calls the client with the screenshot parameter set to True. If response.ok is true, the code writes response.content to ./screenshot.png and breaks out of the loop. If the response is not OK, it prints response.content and continues to the next attempt. The loop bound prevents an endless retry cycle.
Decision checklist before you retry
Use this checklist to keep the retry behavior predictable:
- Confirm the failure signal: the API returns a 500 status code for failed requests and does not charge for them.
- Set a finite bound: choose a MAX_RETRIES value instead of retrying forever.
- Define success: treat response.ok as the stop condition.
- Decide what to do with the body: save response.content only after success; print it on failure for inspection.
- Choose the output path: the example writes to ./screenshot.png.
- Keep the request inputs explicit: the example passes params={'screenshot': True}.
Worked example: screenshot request with a retry cap
The example initializes the API client with an API key and runs a loop capped at five attempts. Each attempt requests a screenshot of the target page. When the response is OK, the screenshot bytes are written to ./screenshot.png and the loop exits. When the response is not OK, the response content is printed and the next attempt begins. This keeps the output file tied to a successful response rather than to a failed one.
Failure versus empty success
A 500 status code means the request failed and is not charged. That is different from a request that returns successfully but produces content you did not expect. The loop only distinguishes success from failure through response.ok; it does not inspect the screenshot for visual correctness. If you need to validate the image or page content, add a separate check after the file is saved.
Request and output map
Request input: the client call uses the target URL and params={'screenshot': True}. Loop control: MAX_RETRIES = 5 sets the maximum number of attempts. Success branch: response.ok triggers writing response.content to ./screenshot.png and breaking the loop. Failure branch: the response content is printed and the loop continues until the cap is reached.
Frequently asked questions
What status code means the request failed?
The API returns a 500 status code for failed requests and does not charge for them.
How many retries does the example allow?
The example sets MAX_RETRIES to 5, so the loop runs at most five times.
When is the screenshot file written?
The file ./screenshot.png is written only when response.ok is true; the loop then breaks.
What happens on a failed attempt?
The code prints response.content and continues to the next attempt, up to the retry cap.