Common errors and fixes
Record the time, model, HTTP status and full error message. The same status can have several causes; the response body provides more context.
401: Authentication failed
Common messages include Invalid token and invalid_api_key.
- Use a Guangji model API key, not your login password or profile access token.
- Copy the entire key without masking, whitespace or extra newlines.
- Check that it is enabled, unexpired and not deleted.
- For the compatible endpoint, include
Authorization: Bearer YOUR_KEY.
If an endpoint uses a different authentication format, follow its own specification.
403: Access denied
Check model restrictions, IP allowlists, account status and group permissions. Site security measures can also reject requests. Inspect the response and provide the request ID to support if needed.
404: Incorrect address or model
- Check the domain, path and HTTP method.
- Remove duplicate
/v1/v1segments and avoid console URLs. - Copy the model ID again and verify group availability.
If the response is HTML instead of JSON, inspect the address and network intermediaries. That symptom alone does not identify a single cause.
429: Request limited
This may involve request frequency, token rate, current load or an upstream limit. Reduce concurrency and frequency, and respect Retry-After when provided. Bound your retries rather than continuously resending.
Insufficient quota
Check account balance, remaining key quota, key status and expiry. For subscriptions, also check quota, validity and billing preferences.
A positive balance does not guarantee that a particular key has available quota. See key management.
No available channel or model
Check the model ID, key group, restrictions and announcements. Users do not need to configure server channels. If the problem persists, contact support.
400: Invalid parameters or context
Check JSON syntax, required fields, supported parameters and protocol. Reduce history, attachments or output length for context errors. Start with a minimal text request to isolate complex parameters.
Timeouts, Failed to fetch or 5xx
Check connectivity, DNS, proxy settings and the request URL, then retry a limited number of times. Browser applications also need HTTPS and cross-origin compatibility. Production applications should keep keys and requests on the server.
A timeout does not mean the request was never executed. Check existing results and logs before retrying.
Still stuck?
Use the support template, with redacted screenshots. Never include a complete API key.