Developer guides · API access

# AI API error guide: 401, 403, 404, 429 and 503

Troubleshoot Xinghuo API authentication, model permissions, endpoint mistakes, rate limits and temporary service errors with a concise diagnostic checklist.

Xinghuo AI Gateway · Updated 2026-10-09

Record the request time and time zone, HTTP status, endpoint, model and returned error code. Keep a request ID if available. Never publish the Authorization header or complete key.

## Start with the status code

| Status | Check first | Action |
| --- | --- | --- |
| 401 | Missing, incorrect or expired key | Check Bearer authentication, whitespace and stale client settings |
| 403 | Group, model or policy permission | Compare key permissions with the response explanation |
| 404 | Endpoint or model ID | Check duplicate /v1 and the exact model name |
| 429 | Concurrency, request rate or quota limit | Read the error, reduce concurrency and honor Retry-After when present |
| 502 / 503 | Temporary service or network failure | Wait briefly, bound retries and contact support if persistent |

## What does SVC_1001 mean?

This site error signals temporary service unavailability. It does not by itself establish that your key balance is depleted. Check balance and usage, then share the time, model and request ID with support.

## Endpoint errors versus model errors

Use `GET /v1/models` to inspect key model access. Chat Completions uses `POST /v1/chat/completions`. Claude Code uses [Messages gateway configuration](https://ai.wfpromax.xyz/guides/en/claude-code.html). If a request returns HTML instead of JSON, check for a web URL, login page or proxy error.

## Streaming disconnects

Record the received output, duration and client timeout. A disconnect can occur in the client, network or server. Reproduce with shorter input and smaller output, then compare non-streaming behavior. Inspect usage before repeating a long task.

## Useful support details

- Request time, time zone, endpoint, status and error code.
- Exact model ID, streaming setting, client name and version.
- A minimal redacted request and request ID, where available.
- Whether a short request reproduces the issue.

For first-time setup use the [quickstart](https://ai.wfpromax.xyz/guides/en/openai-compatible-api.html); for costs use the [billing guide](https://ai.wfpromax.xyz/guides/en/token-billing.html).

## Choose a model. Connect your application.

Check current model access and account pricing, then register and buy the credits you need.

 [View models & pricing](https://ai.wfpromax.xyz/available-channels?entry=guide_en_api-errors) [Buy credits](https://ai.wfpromax.xyz/purchase?entry=guide_en_api-errors) [Create an account →](https://ai.wfpromax.xyz/register?entry=guide_en_api-errors)

## Related guides

[What is Xinghuo AI Gateway? API access, models and service scope](https://ai.wfpromax.xyz/guides/en/service.html)[OpenAI-compatible API quickstart: base URL, key and model](https://ai.wfpromax.xyz/guides/en/openai-compatible-api.html)[Claude Code gateway setup: base URL, authentication and model](https://ai.wfpromax.xyz/guides/en/claude-code.html)[AI API token billing explained: input, output and cache](https://ai.wfpromax.xyz/guides/en/token-billing.html)[AI API buying guide: models, pricing, credits and redemption](https://ai.wfpromax.xyz/guides/en/buying-guide.html)[How to choose GPT, Claude, Gemini or Kimi API models](https://ai.wfpromax.xyz/guides/en/model-selection.html)[ChatGPT and Claude subscriptions vs API credits: what is different?](https://ai.wfpromax.xyz/guides/en/api-vs-subscription.html)