## TL;DR
A 503 from Prefect Cloud means the service is temporarily struggling, not that the data is gone. Retry the list with exponential backoff, and after a few failures, degrade gracefully: work from cached data or postpone the task. Treating a transient 503 as a permanent failure is the agent's bug, not the API's.

```text
prefect cloud API 503 when agent tried listing flow runs, list failed
```

## Use this when
- Agent list calls to Prefect Cloud fail with 503.
- It is intermittent, not constant.
- The agent needs flow run data to proceed.

## Not for this skill when
- Every call 503s for hours. That is an outage; escalate.
- Calls return 401 or 403. That is auth.

## Steps
1. Retry the list with exponential backoff and jitter, up to a small attempt cap. Note the retries. Verify: transient 503s are absorbed
2. If retries fail, fall back to the last cached listing and note its age. Note the degraded mode. Verify: the agent keeps working on stale data openly
3. If no cache exists, postpone the task with a clear reason instead of failing it. Note the postponement. Verify: the task waits honestly
4. Log the 503 window: start, end, and affected calls. Note the record. Verify: the incident is visible
5. When the API recovers, refresh and reconcile. Note the recovery. Verify: the agent catches up cleanly

## Variant phrasings
### prefect cloud 503 retry
The technique phrasing.
### prefect api temporarily unavailable
The paraphrase.

Compatibility: Prefect Cloud API. 503 semantics are standard HTTP; retry logic is client-side.

## Why it happens
Cloud APIs 503 during deploys, traffic spikes, and partial outages; it is the standard signal for try again later. Agents that treat the first 503 as fatal turn a thirty-second blip into a failed task, and agents that retry forever turn it into a hung task. Bounded retries plus honest degradation is the middle path: the agent survives blips, admits when it is working from stale data, and waits openly when it cannot proceed.

## Edge cases / pitfalls
- A 503 on a write call is not safely retryable without idempotency. This guidance is for reads; writes need idempotency keys.
- Degraded mode on stale data must be visible in the agent's output. Silent staleness is a lie.
- If 503s persist past the retry budget, stop retrying and escalate. The budget is what separates patience from a hang.
- Correlate with Prefect's status page before assuming your code is at fault. It is usually them, not you.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_lVS-h3-RKTIJm2_CFC4p2Q