← Documentation home

FAQ and Troubleshooting

API errors and troubleshooting

Use this page to diagnose failed calls. HTTP status, error / message / code / success, and upstream text can vary by endpoint. Treat the current response as the source of truth; do not treat one upstream error code as a permanent contract.

Check in this order

  1. Check the HTTP status. A client timeout, connection reset, or TLS/DNS failure may have no HTTP status at all.
  2. Read the full response: error, message, code, or success: false. A streaming call may return HTTP 200 first and then send an error in SSE.
  3. Save request_id from the response headers or body. This is the most useful locator when you contact support.
  4. Then open usage logs. Failed calls often have no consume row. That does not mean the platform never received the request.

Why usage logs are often empty

  • Consume: records calls that were billed or fully settled. A client-side 401, 403, or 504 usually has no consume row and no deduction.
  • Error: records only some failures that already reached an upstream channel. This type can also be empty.
  • Refund: appears only after a charge is later returned.
  • So a downstream error with no matching usage-log row is often expected. Use the client status, error body, and request_id.
  • These failures are especially likely to leave no usage log: invalid Key, disabled account or Key, IP restriction, model not allowed on the Key, insufficient quota, edge timeout, or the client disconnecting first.
  • For async image or video tasks, check task logs rather than ordinary consume logs.

HTTP status codes

  • 400 invalid request: JSON, required fields, protocol, or model parameters are wrong. Retry with short text and streaming/attachments off. If the model is unpriced, switch to a priced public model or ask an administrator to price it.
  • 401 unauthorized: missing Key, incomplete copy, extra spaces or a wrong prefix, expired or deleted Key. The header must be Authorization: Bearer <API Key>. Never send a complete Key in a screenshot or ticket.
  • 403 forbidden or denied: read the error body, not only the number:
  • Account or Key disabled: check account status and API Key status in the console.
  • Insufficient quota: top up or wait for plan quota to recover.
  • Model not allowed on this Key: switch to an allowed model or change the Key model scope.
  • IP not allowed: call from an allowed network, or ask an administrator to update the Key IP list.
  • Group denied or deprecated: switch groups or ask an administrator to enable access.
  • Upstream 403: the account and Key can still look healthy while upstream temporarily refuses. Keep request_id, retry once with a short request, then contact support if it keeps failing.
  • 404 endpoint or model not found: use the public platform model name, not an upstream internal name. Check that the client did not duplicate /v1 or use the wrong path.
  • 408 request timeout: the call did not finish in time. Shorten context, remove attachments, check the client timeout, and retry once.
  • 413 payload too large: reduce context, images, files, or video input.
  • 429 rate limit: stop burst retries, wait, then send one short request. Check Key or account rate, count, and concurrency limits.
  • 500 internal error: keep request_id and retry once with a short request. Do not replay the same failed request indefinitely.
  • 502 / 503 upstream or channel unavailable: no usable channel for the model, or upstream did not respond. Wait, retry once with a short request, then contact support if it continues.
  • 504 gateway timeout: the call was cut off before completion. The client timeout may be shorter, the network may have dropped, or platform/upstream processing took too long. Usage logs often have no matching row. Increase the client timeout, try a short non-streaming request, drop large context and attachments, and do not immediately hammer the same long request.

No status, or HTTP 200 that still failed

  • Connection reset / TLS / DNS failure: confirm Base URL is https://www.zltokens.com/v1, then change network or disable a buffering proxy.
  • Client timed out first: the local client deadline is shorter than processing time. Raise the client timeout and verify with a short request.
  • Streaming HTTP 200, then SSE error: treat the SSE error as failure. Disable stream to verify the model and Key.
  • Empty response: compare with a short non-streaming request and check whether a proxy truncated the body.
  • Sensitive-content block: edit the prompt; do not resubmit the same blocked text.
  • Async image/video task fails later: check task logs for status and any refund.

Self-serve steps

  1. Send one short text on a low-cost text model with streaming, images, files, and long context off.
  2. After that succeeds, add the original parameters back one at a time.
  3. Do not retry the same failure at high frequency.
  4. If it still fails, contact support with the checklist below.

Before contacting support

Provide time and time zone, request_id, endpoint path, public platform model name, client name and version, whether streaming was used, HTTP status (or “no status”), and a sanitized error body. Do not send API Keys, passwords, complete payment data, or unnecessary prompts and business data.