> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.usglobalmail.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.usglobalmail.com/_mcp/server.

# Bad gateway

Returned as `application/problem+json` with `code` `bad_gateway` and HTTP status `502`.

An upstream service the gateway depends on returned an invalid or unexpected response.

## Common causes

* A downstream service failed or returned something outside its contract.

## How to resolve

* Usually transient — retry with backoff.
* If it persists, contact support with the `request_id`.

## Check system status

A `502` is a server-side failure, so it may reflect a known incident rather than a problem with your
request. Check the [System status page](/guides/core-concepts/system-status) — if there's an open
incident affecting the USGM API or USGM Core, the issue is on our side, so wait for it to resolve. If
everything is operational and the error persists, contact support with your `request_id`.

## Example

```json
{
  "type": "https://docs.usglobalmail.com/api/problems/bad_gateway",
  "title": "An upstream service returned an invalid response.",
  "status": 502,
  "code": "bad_gateway",
  "request_id": "req_8f3c2a1b9d",
  "instance": "/v1/mails"
}
```

> **Note**
>
> This error is typically transient — safe to retry with exponential backoff.