Skip to main content

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

1

Step 1: Wait 30-60 seconds, then resend the request

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.
2

Step 2: If the web console won't load, force-refresh the page

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.
3

Step 3: If the 502 persists for more than 5 minutes, contact support

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.
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.
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, 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.
  • 429: Concurrency or rate limit reached; unrelated to service availability. See API Concurrency Limits.
  • 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 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.
If everything still returns 502 on a different network for more than 5 minutes, contact support.

How to Avoid API Timeouts

Timeout settings, reasoning-model latency, and 524 diagnosis

Do I Need a Proxy to Use the API?

Direct-connection notes and network requirements

Where Are APIYI's Servers?

Node locations, latency testing, and purchase advice

Service Availability and SLA

Availability commitments and incident response

Contact Us

WeCom Support

WeCom support QR codeScan the QR code, or click this card to reach support directlyPersistent 502 reports and incident triage

Email