Skip to main content

​
Short answer

Do not diagnose a request from the HTTP status code alone. Save the full error, model name, Base URL, token group, and request ID first, then determine whether the problem is a request configuration error or a temporary upstream failure:
  • 400, 401, 403, unsupported parameters, safety blocks, and group mismatches usually require a request or configuration change. Repeating the same request will not fix them.
  • 429, 503, some 504 responses, and Upstream model timed out can be caused by upstream load, resource availability, or long-running requests. Check the logs, then use limited exponential-backoff retries.
  • If only one model or group fails, test an authorized fallback group. If several models fail at once, check your API key, Base URL, and network path first.

​
Save the complete error

Screenshots often omit the most useful fields. Keep the following information before troubleshooting:
Never expose a complete API key in a ticket, screenshot, or code sample. Keep only the error message, request ID, and redacted configuration.

​
Troubleshoot by error type

The same status code can have different causes. For example, 429 may mean upstream saturation, but it can also be a request-compatibility problem whose details appear only in the full error message. Use the response body and call logs as the final evidence.

​
Standard troubleshooting steps

1

Step 1: Reproduce with a minimal request

Temporarily remove optional parameters, tool definitions, complex image inputs, and long prompts. Keep only the model, required messages, and authentication information. This separates request errors from route or model errors.
2

Step 2: Verify the endpoint, token, and group

Make sure the API key is used with the api.apiyi.com Base URL. In the console, check the token’s primary group, fallback group, and allowed models. Some models require a dedicated group.
3

Step 3: Decide whether a retry is appropriate

Use backoff retries for 429, 503, and confirmed temporary upstream failures. For parameter errors, safety blocks, invalid model names, and group mismatches, change the request or configuration instead of retrying unchanged.
4

Step 4: Check timeout and network path

Image generation, reasoning models, and long text requests need larger timeouts. Use api.apiyi.com or vip.apiyi.com for long requests instead of the api-cf.apiyi.com CDN node, which has an approximately 100-second limit.
5

Step 5: Check call logs before resending

Check whether the request created a charge record. A client timeout or disconnect does not always mean that server-side processing stopped; avoid blindly sending the request again before confirming its status.

​
Minimal test request

Use the following request to verify the endpoint, token, and basic model call. Replace YOUR_MODEL with a model available to your token, and do not add optional fields until the minimal call works.

​
Prevent recurring errors

  • Start with a minimal request, then add stop, tools, reasoning controls, images, and other optional fields one at a time.
  • Maintain a parameter-compatibility table for your models instead of assuming that every model supports the same fields.
  • Do not immediately resend many concurrent requests after a 429; use exponential backoff and control concurrency per model.
  • Give image and reasoning requests enough timeout. Avoid stacking SDK retries with your own business-layer retries.
  • Configure a fallback group that has been tested with your actual production parameters.

​
Frequently asked questions

No. 429 can come from concurrency or upstream saturation, but the error message may also hide a parameter-compatibility issue. Read the complete error.message before deciding whether to lower concurrency or change the request.
No. First confirm that the request uses APIYI’s Base URL, then check whether the token has expired and whether the correct group is selected. If only one model returns Invalid token alongside 5xx or timeout errors, the upstream route may also be the cause.
Check the call logs first. A client timeout only means that the client stopped waiting; server-side processing may still continue. If the request has a charge record, an immediate retry can create a duplicate call.
Do not rely on the error page alone. Parameter validation, authentication, and safety blocks that never reach model generation usually do not create a final charge, but a client disconnect or a request that has already started upstream processing may still be charged. Use the call logs as the source of truth.

​
Still stuck? Contact support

If the issue persists after the steps above, contact APIYI support through WeCom or email. Include the following information to speed up troubleshooting:
  • Model name, token group, and Base URL
  • Full error message, HTTP status, and request ID
  • Time of occurrence, including the UTC+8 time zone
  • A minimized request example or a redacted request body
  • Whether the call logs contain a charge record
Never send a complete API key. Keep only the prefix and last few characters visible, and redact the rest.

WeCom Support

Scan the QR code, or click this card to contact support directly.Model errors, timeouts, groups, and billing issues

Email Support

Support: [email protected]We recommend including “model error” and the model name in the subject.

Why is my API key invalid?

Check the Base URL, API key, and authentication settings

What are groups?

Learn about token groups, upstream routes, and fallback groups

How can I avoid request timeouts?

Configure timeouts, nodes, and long-request troubleshooting

How much concurrency can I use?

Review model concurrency limits and 429 guidance

What should I do when the site or API returns 502?

Understand 5xx errors, retries, and billing checks

How do I read billing amounts in the logs?

Use call logs to confirm whether a request was charged