> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryaeris.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Upstream unavailable (UPSTREAM_UNAVAILABLE)

> A partner API returned 5xx, or the network hop to it failed. Retryable.

## What it means

Aeris tried to reach a partner service (Google Ads, Meta, Microsoft, BigQuery, Stripe, ...) and got a 5xx, a DNS error, or a TLS handshake failure. This is a transient upstream fault, not a client bug — the same request will most likely succeed shortly.

## How to fix

* Wait at least `retry_after_ms` (default 5000ms) and retry.
* If retries keep failing over minutes, check the partner's public status page — `details.upstream` tells you which one.
* For write actions with an `idempotency_key`, safely retry the exact same call; Aeris will not double-apply.

<Note>
  `retry_after_ms` is currently advisory. The Worker may honour it directly or apply its own circuit-breaker logic in front of it.
</Note>

## Response envelope

```json theme={"dark"}
{
  "ok": false,
  "error_envelope": {
    "code": "UPSTREAM_UNAVAILABLE",
    "message": "The upstream service is currently unavailable.",
    "docs_url": "https://tryaeris.ai/docs/mcp/errors/upstream-unavailable",
    "retryable": true,
    "retry_after_ms": 5000,
    "details": {
      "upstream": "google_ads"
    }
  }
}
```

## Related

* [`TIMEOUT`](/mcp/errors/timeout) — upstream never answered inside our budget.
* [`CONNECTION_EXPIRED`](/mcp/errors/connection-expired) — upstream refused because auth is stale.
* [`INTERNAL`](/mcp/errors/internal) — fault inside Aeris, not the partner.