Recover from API errors

Do not start guessing as soon as you see an error. Record the HTTP status and one non-sensitive error message, then change one thing at a time.

Start with the status code

What you see	Check first	First action
400 Bad Request	JSON, required fields, request format	Compare model and messages with the minimal example
401 Unauthorized	Token and authorization header	Copy the Token again and use Authorization: Bearer
403 Forbidden	Token access or account availability	List /v1/models again with the same Token
404 Not Found	Base URL and endpoint joining	Look for a missing or repeated /v1 or /chat/completions
429 Too Many Requests	Token quota, account balance, or request rate	Check the portal, then wait or reduce concurrency as appropriate
5xx	The service could not complete the request	Keep the timestamp and status, then retry once later
Timeout or connection failure	Address, DNS, proxy, certificate, network	Request https://api.zhiflo.com/v1/models to isolate the layer

If the model is missing or unavailable

This condition does not always use one status code. Call GET /v1/models with the same Token, copy a complete data[].id, and replace the request’s model value.

Do not use a similar-looking name from search results. Capitalization, slashes, hyphens, and suffixes must all match.

If you get 404

When a client asks for a Base URL, the usual value is:

https://api.zhiflo.com/v1

The client appends /chat/completions or /responses. Only use the full Chat Completions endpoint when a field explicitly asks for one:

https://api.zhiflo.com/v1/chat/completions

Claude Code is the exception: ANTHROPIC_BASE_URL is https://api.zhiflo.com, and Claude Code appends /v1/messages.

If model listing works but generation fails

The address and basic Token authentication have already worked. Check only these next:

1. The model ID came from the response you just received.
2. The selected client protocol matches the endpoint.
3. The POST body is valid JSON with the fields required by that endpoint.
4. The Token quota and account state permit the request.

Information that is safe to keep

For troubleshooting, record the request time, HTTP method, path, status, request ID, client name, and redacted settings. Never send the full Token, a private conversation, an unredacted screenshot, or a credential-bearing configuration file.

Next: for a problem without a clear HTTP status, troubleshoot the connection by symptom.