Relay returns 502 or 504: where the break is

How to tell an upstream failure from a relay gateway timeout, and when retrying is safe.

Reviewed 2026-11-12 · Chinese detail: 完整中文页

What 502 and 504 mean here

502 means the relay could not get a valid response from its upstream. 504 means the relay waited for the upstream and gave up. In both cases the break is between the relay and the provider, not in your client.

Check in order

1. Try a different model on the same relay. If it works, the issue is the upstream route for that model.

2. Try a different relay. If it also fails, the upstream provider may be down.

3. Check the relay's status page and announcement channel.

4. Try again after a few minutes. Gateway timeouts are often transient.

Retry safely

Retry 502 and 504 with a short backoff and a small attempt cap. For non-streaming requests, use an idempotency key if the relay supports one; otherwise a retry after a timeout may be billed twice. For streaming requests, check whether the stream started before deciding to retry.

When to open a ticket

If one model fails consistently while others work, send the relay the model name, timestamps, request IDs, and the exact error body. Do not send your API key.

This page is general guidance, not a statement about any specific provider. For measured data, see the relay directory and method.