When troubleshooting API errors, log them first Status code, response body, request ID, model name, and time of occurrence. Just looking at the words "call failed", it is difficult to determine whether the problem is located on the client, the gateway, or the upstream model.
Check before you start
Reproduce with minimal requests, temporarily turning off streaming output, tool calls, and long contexts. After confirming that the short request also failed, enter the status code troubleshooting.
curl https://www.aifast.club/v1/models \
-H "Authorization: Bearer $AIFAST_API_KEY" \
-iConfiguration steps
401 Unauthorized
401 means authentication failed. Check in order:
- Whether the Key is complete, valid and belongs to the current account.
- Whether the request header is
Authorization: Bearer ...。 - Whether there are spaces, newlines or extra quotation marks before and after Key.
- Whether the client automatically adds
Bearer, leading to duplication. - Whether the environment variable takes effect in the current process.
401 should generally not be retried automatically. When the authentication information remains unchanged, retrying will only result in repeated failures.
When you need to check request headers, environment variables, and configuration overrides item by item, check out401 invalid_api_key complete troubleshooting。
429 Too Many Requests
429 may mean:
- The request frequency exceeds the limit.
- The number of concurrency is too high.
- The account balance or quota is insufficient.
- The specific model is busy.
Processing sequence: reduce concurrency, increase exponential backoff, check balance and usage, and then confirm whether only a single model is affected.
No. 1 wait times 1 seconds
No. 2 wait times 2 seconds
No. 3 wait times 4 seconds
Stop after reaching the upper limit，No infinite retriesFor the handling methods of batch processing, Agent and multi-layer SDK retries, see429 Too Many Requests Complete Troubleshooting。
502 Bad Gateway
502 usually occurs when the gateway cannot get a valid response from upstream. Common reasons:
- The upstream model is temporarily abnormal.
- Long task exceeds agent timeout.
- Streaming connection interrupted.
- The request body is too large or the context is too long.
- The gateway is incompatible with the upstream protocol.
First switch to short input, turn off streaming output and keep the same model test. If a short request succeeds but a long request fails, the timeout and context are checked first instead of the Key.
if appears stream disconnected、upstream connect error Or just interrupt in streaming mode, viewComplete troubleshooting of 502 and SSE disconnection。
504 or client timeout
Distinguish three types of timeouts:
| timeout type | meaning |
|---|---|
| Connection timeout | Unable to establish network connection in time |
| Read timeout | Connected, but no new data for a long time |
| total task timeout | The entire task exceeds the time allowed by the business |
The agent task may temporarily have no text output when executing the tool, and the read timeout cannot be set as short as a normal chat.
FAQ
Should we try again on any errors encountered?
It shouldn't be. Suggestions:
- 401, 400, model does not exist: correct the configuration and do not try again.
- 429. Partial 5xx, brief network interruption: limited retry.
- Tool calls with side effects: ensure idempotence first, then consider retrying.
What do you need to provide to customer service?
Provide time of occurrence, model ID, status code, request ID, and masked error text. Do not send the complete API Key, and do not paste user private data directly into the work order.
Next step
Establish a unified error log and put the request ID, model, time consumption, input and output tokens, number of retries and final status in the same record. This way you can determine whether an error is an occasional issue or a persistent problem.