← Documentation home

FAQ and Troubleshooting

API errors and troubleshooting

This page is the single place to diagnose failed calls. HTTP status, error / message / success fields, and exact messages returned by upstream channels can vary by endpoint and channel. Do not treat one upstream error code as a permanent client-side contract.

Check in this order

  1. Check the HTTP status.
  2. Check the full response for error, a failure message, or success: false. Treat the call as failed when the business response reports failure, even if HTTP is 200.
  3. Use request_id, time, model, and endpoint to find the request in usage logs.

Common cases

  • 400 invalid request: Check the Base URL, endpoint path, protocol, JSON format, and required parameters. Reproduce with a short non-streaming request before adding large context, files, or images.
  • 401 unauthorized: Confirm Authorization: Bearer <API Key>, a complete Key, no extra spaces or invalid prefix, and that the Key is still active. Never send a complete Key in a screenshot, ticket, or chat.
  • 403 forbidden: Check whether the account or Key is disabled and whether model, group, or IP restrictions allow the call. Ask an administrator to resolve restrictions customers cannot change.
  • 404 endpoint or model not found: Use the public platform model name rather than an upstream internal name. Also check that the client did not duplicate /v1 or use an incorrect endpoint path.
  • 429 rate limit or quota: Stop burst retries, wait, then retry once with a short request. Check available quota, rate limits, and concurrency limits.
  • 5xx, network failure, or timeout: The cause can be upstream, channel, or network. Keep the request_id and make one short, low-cost retry; do not replay the same failed request indefinitely.
  • Non-streaming works but streaming fails: First confirm a short non-streaming request, then verify streaming support and response buffering in the client, proxy, and selected channel.

Before contacting support

Provide the time and time zone, request_id, endpoint path, public platform model name, client name and version, whether streaming was enabled, HTTP status, and a sanitized response or screenshot. Do not provide API Keys, passwords, complete payment data, or unnecessary prompts and business data.