> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apiyi.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Website or API Returns 502 — What Should I Do?
> A 502 is a brief symptom of a service container auto-restarting, usually resolved within 1 minute — failed calls are never billed, and a 30-second client retry rides it out seamlessly
## Quick Answer
**A 502 is transient — no configuration changes are needed on your side:**
1. **The root cause is an automatic service container restart** — during the restart window the web console is unreachable and the API returns 502; they are the same event.
2. **Recovery is usually automatic within 1 minute** — wait 30-60 seconds and resend your request.
3. **Failed calls are never billed** — during a 502 the request never actually reaches the service, so no billing record is created.
4. **Add automatic retries on the client side** — a single retry after about 30 seconds rides out the entire restart window seamlessly.
## What Is Happening
`502 Bad Gateway` means: **the gateway layer received your request but got no response when forwarding it to the backend service**.
On APIYI, the vast majority of transient 502s are caused by **an automatic restart of the backend service container**. While the backend process is briefly unavailable:
* **The web console** (dashboard, top-up pages, etc.) fails to load or shows errors
* **The API** (`api.apiyi.com` and all other endpoints) returns 502
Both are backed by the same service, so they **fail together and recover together**. Once an anomaly is detected, the system completes the restart automatically — the whole process **usually finishes within 1 minute** with no manual intervention.
**This kind of 502 has nothing to do with your code, Key, balance, or network configuration.** If this is your first time seeing it, there is nothing to debug on the client side — wait 30-60 seconds and retry; in the vast majority of cases the service has already recovered.
## What You Should Do
A container restart usually completes within 1 minute. Simply resend your API call — since failed calls are never billed, retrying will not cause duplicate charges.
After recovery your browser may still show a cached error page. Use **Ctrl+Shift+R** (Windows) or **Cmd+Shift+R** (Mac) to force-refresh and see the normal interface.
A transient restart never lasts more than a few minutes. If the 502 **persists for more than 5 minutes**, it is not a routine auto-restart — please reach out via the contact options at the bottom of this page, including the approximate time it occurred (with timezone, e.g. `14:30 (UTC+8)`).
## Adding Automatic Retries to Programmatic Calls
If your workload is availability-sensitive, add automatic retries for transient errors like 502 on the client side — one retry after about 30 seconds covers the entire restart window.
```python theme={null}
import time
from openai import OpenAI, InternalServerError
client = OpenAI(
api_key="YOUR_API_KEY",
base_url="https://api.apiyi.com/v1",
max_retries=0, # disable SDK default retries; the logic below takes over
)
def chat_with_retry(messages, retries=2, wait=30):
for attempt in range(retries + 1):
try:
return client.chat.completions.create(
model="gpt-4o",
messages=messages,
)
except InternalServerError:
# 502 / 503 and other 5xx: the request never reached the
# service and is not billed, so retrying is always safe
if attempt == retries:
raise
time.sleep(wait) # restarts finish within ~1 min; wait 30s
resp = chat_with_retry([{"role": "user", "content": "Hello"}])
print(resp.choices[0].message.content)
```
```javascript theme={null}
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.APIYI_API_KEY,
baseURL: "https://api.apiyi.com/v1",
maxRetries: 0, // disable SDK default retries; the logic below takes over
});
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
async function chatWithRetry(messages, retries = 2, waitMs = 30_000) {
for (let attempt = 0; ; attempt++) {
try {
return await client.chat.completions.create({
model: "gpt-4o",
messages,
});
} catch (err) {
// 502 / 503 and other 5xx: the request never reached the
// service and is not billed, so retrying is always safe
if (err.status < 500 || attempt >= retries) throw err;
await sleep(waitMs); // restarts finish within ~1 min; wait 30s
}
}
}
const resp = await chatWithRetry([{ role: "user", content: "Hello" }]);
console.log(resp.choices[0].message.content);
```
```bash theme={null}
# curl's --retry automatically retries transient errors like 502/503/504
curl https://api.apiyi.com/v1/chat/completions \
--retry 2 --retry-delay 30 \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o",
"messages": [{"role": "user", "content": "Hello"}]
}'
```
**Only apply this retry strategy to 502/503-style errors where the request never reached the service.** Requests that were cut off by a client timeout (or a `524`) may still be running on the server side and are billed normally — blindly retrying those causes duplicate charges. For that class of problem, see [How to Avoid API Timeouts](/en/faq/timeout-configuration).
For high-frequency workloads you can also probe quickly with **exponential backoff** (1 second, then 2, then 4) — network-blip 502s usually clear within seconds. If those attempts still fail, fall back to the 30-second interval to cover the container-restart case.
## Frequently Asked Questions
**No.** A 502 means the request never actually reached the backend service — no model usage occurred, so **nothing appears in your billing records**.
This is also a handy diagnostic: if a failed request has no billing entry in your [call logs](/en/faq/call-logs), it was never processed server-side, and you can safely resend it.
* **`502`**: The backend service is briefly unavailable (container restarting). Wait 30-60 seconds and retry; not billed.
* **Timeout / dropped connection**: Your client timeout is too short — the server may still be running the request and billing it normally. See [How to Avoid API Timeouts](/en/faq/timeout-configuration).
* **`429`**: Concurrency or rate limit reached; unrelated to service availability. See [API Concurrency Limits](/en/faq/api-concurrency).
* **`524`**: You are on the CDN endpoint (`api-cf.apiyi.com`) with a request exceeding roughly 100 seconds — switch endpoints.
These call for completely different responses: **only 502/503 should be retried directly**.
The web console and the API are backed by the same service. During a container restart both become **unavailable together and recover together** — so "the website is down too" is exactly what confirms this is a transient platform-side event, not a problem with your client configuration.
No — it is not a regular occurrence. Transient 502s are typically tied to sudden traffic spikes and are sporadic.
**As of August 2026 we are upgrading and scaling up the backend servers**, which will significantly reduce the frequency of these transient 502s. Whenever there is a platform-side incident, we publish status updates and recovery progress on the [live status feed](/en/live) right away.
Two quick checks:
1. **Open the web console**: if `api.apiyi.com` returns 502 and the console also fails to load, it is almost certainly a transient platform-side restart — wait a minute.
2. **Switch networks**: try mobile data (a different carrier) to load the console, or run the command below. If it works there, the problem is your local network or proxy.
```bash theme={null}
curl -I https://api.apiyi.com/v1/models \
-H "Authorization: Bearer YOUR_API_KEY"
```
If everything still returns 502 on a different network for more than 5 minutes, contact support.
## Related Documentation
Timeout settings, reasoning-model latency, and 524 diagnosis
Direct-connection notes and network requirements
Node locations, latency testing, and purchase advice
Availability commitments and incident response
## Contact Us
Scan the QR code, or click this card to reach support directly
Persistent 502 reports and incident triage
**Support**: [support@apiyi.com](mailto:support@apiyi.com)
**Business**: [business@apiyi.com](mailto:business@apiyi.com)