Synchronous GitHub API call with client‑side timeout versus Prefer: respond‑async with polling for cancellable long‑running jobs

Direct answer

A synchronous GitHub API request with a client‑side timeout provides more reliable enforcement of a maximum wait time than using Prefer: respond‑async and polling.

Likely explanation (why)

The synchronous method aborts the HTTP connection as soon as the client‑side timeout expires, returning a timeout error immediately. The async method relies on the client ending a poll loop; stopping the poll does not halt the server‑side job, so the timeout is only a best‑effort cancellation.

Confirmed facts (from research)

1. A synchronous call uses a single HTTP request (plus any automatic retries); the client‑side timeout directly aborts the wait.
2. Using Prefer: respond‑async returns 202 Accepted with a Location URL; each poll consumes one rate‑limit unit and there is no dedicated cancel endpoint.
3. Frequent polling (e.g., every 5‑10 s) can noticeably increase rate‑limit usage, while a synchronous call incurs minimal overhead.
4. A hybrid approach—short timeout on the initial async request, then polling with exponential backoff and an overall deadline—balances bounded wait, rate‑limit usage, and best‑effort cancellation.

Steps for this case

1. If reliable timeout is the priority: make a synchronous request and set the desired timeout on the HTTP client (e.g., 30 seconds). Handle the timeout error and treat it as a failure; note that the server may continue the operation.
2. If you need status updates and can tolerate some rate‑limit cost: send the request with Prefer: respond‑async, capture the Location URL, and poll with an exponential backoff (starting at 5 s, doubling up to a max of 30 s). Enforce an overall deadline (e.g., 2 minutes) after which you abort the poll loop.
3. Optional cancellation: after aborting the poll, attempt to delete the associated resource (e.g., delete the deployment or remove the merge‑queue item) to try to stop the server‑side work.

Missing diagnostic detail

To decide whether the hybrid approach’s polling overhead is acceptable, we need to know the typical duration of the long‑running GitHub operation you are targeting (e.g., average time to create a deployment). If jobs usually finish well under your overall deadline, a longer initial poll interval can reduce rate‑limit impact.