Handling 202 Accepted and Refresh Jobs

The flow

GET /v1/refresh/jobs/9f0b7d0f6fd4f88a

HTTP/1.1 200 OK

{"id":"9f0b7d0f6fd4f88a","status":"running","resource_url":"/v1/mods?query=radio","retry_after_seconds":2}

If a refresh-job response includes Retry-After, wait that many seconds before polling the job URL or retrying the original resource.

The rules

• 202 is not an error. If you receive it from a refresh flow, do not log it as a failure or give up on the first response.
• Respect Retry-After. Retrying faster does not speed up the refresh.
• Bound your retries. Three to five attempts is enough for most clients.
• Retry the original URL. The job endpoint reports status only; it does not contain the final data.

Minimal implementation

import time
import requests

def fetch_with_retry(url, max_attempts=4):
    headers = {"User-Agent": "my-tool/2.0.0 ([email protected])"}
    for _ in range(max_attempts):
        response = requests.get(url, headers=headers, timeout=15)
        if response.status_code not in (202, 429, 503):
            response.raise_for_status()
            return response.json()
        wait = int(response.headers.get("Retry-After", "2"))
        time.sleep(wait)
    raise RuntimeError("Still retrying after retry limit")

mods = fetch_with_retry("https://api.reforgermods.net/v1/mods?query=radio")

When to poll the job URL

Poll Location only when you want to display progress, such as queued, running, or succeeded. After succeeded, request the original resource_url again. After failed, back off and retry the original URL later.