User Error Code Guide
This document is intended for platform users and summarizes the internal error codes you may encounter when calling AI model APIs, along with their solutions.
Response Format: Error responses follow the OpenAI format:
{"error": {"message": "...", "type": "neolink_error", "code": "..."}}.How to Locate: Use the HTTP status code to quickly identify the error category, then match the specific error using the
codeormessagefield in the response body.
Table of Contents
- HTTP 400 — Bad Request
- HTTP 401 — Authentication Failed
- HTTP 402 — Insufficient Quota/Balance
- HTTP 403 — Permission/Entity/Cache Denied
- HTTP 404 — Not Found
- HTTP 413 — Request Body Too Large
- HTTP 429 — Rate Limit
- HTTP 500 — Internal Server Error
- HTTP 501 — Not Implemented
- HTTP 503 — Service Unavailable
HTTP 400 — Bad Request
The request parameters are incorrect or the request format has issues. Modify the request and retry.
| code | message | Cause | Solution |
|---|---|---|---|
invalid_request | Invalid request, <specific error details> | Request parameters failed validation, e.g., missing required fields, incorrect field types, or values out of range | Check that the request body conforms to the parameter specification of the corresponding API. Fix according to the specific hints in message and retry |
invalid_request | invalid request type, expected dto.GeneralOpenAIRequest, got %T | Internal request type conversion failed, usually caused by request body structure mismatch | Verify that the request body is in standard OpenAI Chat Completions format, adjust and retry |
invalid_request | invalid request type, expected dto.ImageRequest, got %T | Image generation API request body type mismatch | Confirm that the request body conforms to the image generation API (e.g., DALL·E) parameter specification |
invalid_request | invalid request type, expected dto.RerankRequest, got %T | Rerank API request body type mismatch | Confirm that the request body conforms to the Rerank API parameter specification |
invalid_request | invalid request type, expected *dto.GeminiChatRequest, got %T | Gemini API request body type mismatch | Confirm that the request body conforms to the Gemini Chat API parameter specification |
invalid_request | invalid request type, expected *dto.EmbeddingRequest, got %T | Embedding API request body type mismatch | Confirm that the request body conforms to the Embedding API parameter specification |
invalid_request | invalid request type, expected *dto.ClaudeRequest, got %T | Claude API request body type mismatch | Confirm that the request body conforms to the Claude API parameter specification |
invalid_request | unsupported endpoint %q for api type %d | The requested endpoint path does not match the current API type | Check whether the request path is correct and confirm the endpoint supported by the model/channel |
invalid_request | invalid request type, expected dto.OpenAIResponsesRequest or dto.OpenAIResponsesCompactionRequest, got %T | Responses API request body type mismatch | Confirm that the request body conforms to the OpenAI Responses API parameter specification |
chat_to_responses_unsupported_parameter | this request cannot be bridged from chat completions to responses because it uses unsupported parameter: <params> | When bridging Chat→Responses, the request uses parameters that cannot be expressed by the Responses API (e.g., stop), and the rule is configured as reject | Modify the request parameters, remove incompatible parameters and retry; or contact the administrator to adjust the bridging rule to fallback mode |
sensitive_words_detected | sensitive words detected | The input content triggered the platform's sensitive word filtering rules | Modify the input content, remove sensitive words, and retry |
read_request_body_failed | http: request body too large, unexpected EOF, Failed to read request body: <underlying IO error>, etc. | An IO error occurred while the platform was reading the request body (e.g., body too large, connection interrupted) | Check whether the network connection is stable; confirm that the request body has been fully sent and retry |
model_price_error | The price for model gpt-4 is not configured. Please go to "System Settings → Operation Settings" to enable self-use mode, or configure the price for this model in "System Settings → Group & Model Pricing Settings", etc. | The platform encountered an error querying the model pricing (e.g., pricing not configured, database query failed) | Retry later; if the issue persists, contact the administrator to check the model pricing configuration |
channel:param_override_invalid | Channel parameter override config invalid: invalid character 'x' looking for beginning of value, etc. | The channel's parameter override configuration JSON is malformed | Contact the administrator to check whether the channel's "parameter override" configuration is valid JSON |
| — | Invalid request, <specific error> | The dispatcher encountered an error parsing the request | Fix the request parameters according to the specific hints in message and retry |
| — | Invalid channel ID | The channel ID specified in the request is invalid or does not exist | Check that the correct channel ID is specified in the request; regular users are not allowed to specify a channel |
| — | Model name not specified, model name cannot be empty | The request does not include a model name | Fill in the model name in the model field of the request body and retry |
| — | Invalid playground request, <error> | The Playground request format is incorrect | Adjust the Playground request structure according to the hints in message |
| — | Action query parameter is required | The Jimeng adapter API is missing the Action query parameter | Add the Action query parameter to the request URL |
| — | Invalid request body | The Jimeng adapter API request body format is incorrect | Check that the request body is valid JSON and conforms to the API specification |
| — | task_id is required for CVSync2AsyncGetResult | The task_id was not provided when getting results from sync-to-async | Include a valid task_id parameter in the request and retry |
HTTP 401 — Authentication Failed
The token (API Key) authentication failed. Check the token validity.
| code | message | Cause | Solution |
|---|---|---|---|
| — | Invalid token | The token used in the request does not exist in the platform or has been deleted | Verify the API Key is correct; if unsure, contact the administrator to obtain a new token |
| — | Token has expired | The token has exceeded its validity period | Contact the administrator to renew or apply for a new token |
| — | Token has been deleted | The token has been deleted by the administrator | Contact the administrator to confirm the token status and apply for a new token if necessary |
| — | Token status unavailable | The token status is abnormal (not enabled, not expired, not exhausted) | Contact the administrator to confirm the token status |
| — | Token not provided | The request does not include an API Key | Add Authorization: Bearer sk-xxxx to the request header and retry |
| — | Invalid token, database query error, please contact the administrator | A database error occurred while querying the token | Retry later; if the issue persists, contact the administrator |
| — | This member has been disabled, API calls are not allowed | The enterprise member associated with the token has been disabled | Contact the administrator to enable the member |
| — | This enterprise has been disabled, API Key cannot be used | The enterprise associated with the token has been disabled | Contact the administrator to enable the enterprise |
HTTP 402 — Insufficient Quota/Balance
The quota/balance of the token, member, department, or enterprise is insufficient to complete this request. The following error codes come from the pre-deduction quota validation step. The details field includes remaining quota, requested quota, and other details.
| code | message | Cause | Solution |
|---|---|---|---|
TOKEN_QUOTA_INSUFFICIENT | Token total quota insufficient | The token's remaining total quota is less than the pre-deduction amount for this request | Contact the administrator to recharge the token's total quota |
TOKEN_DAILY_QUOTA_ZERO | Token daily quota is 0, calling is prohibited | The token's daily quota is configured as 0 | Contact the administrator to increase the token's daily quota |
TOKEN_DAILY_QUOTA_EXHAUSTED | Token daily quota exhausted | The token's usage today has reached the daily quota limit | Automatically resets at 00:00 the next day; or contact the administrator to increase the daily quota |
TOKEN_MONTHLY_QUOTA_ZERO | Token monthly quota is 0, calling is prohibited | The token's monthly quota is configured as 0 | Contact the administrator to increase the token's monthly quota |
TOKEN_MONTHLY_QUOTA_EXHAUSTED | Token monthly quota exhausted | The token's usage this month has reached the monthly quota limit | Automatically resets on the 1st of the next month; or contact the administrator to increase the monthly quota |
MEMBER_DAILY_QUOTA_ZERO | Member daily quota is 0, calling is prohibited | The member's daily quota is configured as 0 | Contact the administrator to increase the member's daily quota |
MEMBER_DAILY_QUOTA_EXHAUSTED | Member daily quota exhausted | The member's usage today has reached the daily quota limit | Automatically resets at 00:00 the next day; or contact the administrator to increase the daily quota |
MEMBER_MONTHLY_QUOTA_ZERO | Member monthly quota is 0, calling is prohibited | The member's monthly quota is configured as 0 | Contact the administrator to increase the member's monthly quota |
MEMBER_MONTHLY_QUOTA_EXHAUSTED | Member monthly quota exhausted | The member's usage this month has reached the monthly quota limit | Automatically resets on the 1st of the next month; or contact the administrator to increase the monthly quota |
ORG_MONTHLY_QUOTA_ZERO | Department monthly budget is 0, calling is prohibited | The department's monthly budget is configured as 0 | Contact the administrator to adjust the department's monthly budget |
ORG_MONTHLY_QUOTA_EXHAUSTED | Department monthly budget exhausted | The department's usage this month has reached the monthly budget limit | Automatically resets on the 1st of the next month; or contact the administrator to increase the monthly budget |
ENTERPRISE_BALANCE_INSUFFICIENT | Enterprise balance insufficient | The enterprise account balance is less than the pre-deduction amount for this request | Contact the administrator to recharge the enterprise account |
USER_BALANCE_INSUFFICIENT | User balance insufficient | The user account balance is less than the pre-deduction amount for this request | Contact the administrator to recharge the user account |
HTTP 403 — Permission/Entity/Cache Denied
The request was denied, possibly due to insufficient permissions, invalid entity, cache error, IP restrictions, etc.
1. Quota Exhausted at Authentication Stage
| code | message | Cause | Solution |
|---|---|---|---|
| — | Token quota exhausted TokenStatusExhausted[sk-xxx***xxx] | Token status is exhausted (detected at authentication stage) | Contact the administrator to recharge the token quota |
| — | [sk-xxx***xxx] Token quota exhausted ... | Token remaining quota ≤ 0 (runtime check) | Contact the administrator to recharge the token quota |
2. Entity Lookup/Parameters
| code | message | Cause | Solution |
|---|---|---|---|
TOKEN_INVALID | Token invalid | Token entity is invalid during pre-deduction | Contact the administrator to confirm the token configuration is normal |
MEMBER_INVALID | Member invalid | The member associated with the token has been disabled or does not exist | Contact the administrator to confirm the member status |
ORG_INVALID | Department invalid | The department associated with the token has been disabled or does not exist | Contact the administrator to confirm the department status |
ENTERPRISE_INVALID | Enterprise invalid | The enterprise associated with the token has been disabled or does not exist | Contact the administrator to confirm the enterprise status |
USER_INVALID | User invalid | The user associated with the token has been disabled or does not exist | Contact the administrator to confirm the user status |
ENTITY_NOT_FOUND | Entity not found (Lua fallback message); constructor may generate token not found, user not found, member not found, organization not found, enterprise not found | The corresponding entity (token/member/department/enterprise, etc.) was not found during pre-deduction | Contact the administrator to confirm that the related entity configuration is normal |
INVALID_PARAMETERS | Invalid parameters (Lua fallback message) | Pre-deduction parameter validation failed | Fix the parameters according to the hints in message; contact the administrator if configuration changes are needed |
insufficient_quota | Pre-deduction quota failed, [ERROR_CODE] message, e.g., Pre-deduction quota failed, [TOKEN_QUOTA_INSUFFICIENT] Token total quota insufficient | Pre-deduction validation failed and no specific error code above was matched (generic fallback) | Contact the administrator to troubleshoot the quota configuration and confirm whether the token/member/department/enterprise quota or balance is sufficient |
3. Cache/Script
| code | message | Cause | Solution |
|---|---|---|---|
CACHE_UPDATE_FAILED | Cache update failed | Failed to update the Redis cache during pre-deduction | Retry later; if the issue persists, contact the administrator to check the cache service |
LUA_SCRIPT_EXECUTION_FAILED | Lua script execution failed: pre_consume_personal or Lua script execution failed: pre_consume_enterprise | The Lua script executed during pre-deduction encountered an exception | Retry later; if the issue persists, contact the administrator to check the script configuration |
4. Permission/Access
| code | message | Cause | Solution |
|---|---|---|---|
access_denied | Resource access denied | The token does not have permission to access the requested model resource | Contact the administrator to grant the token access to the corresponding model |
| — | This token does not have access to any models | The token is not bound to any available models | Contact the administrator to assign model permissions to the token |
| — | This token does not have access to model <modelCode> | The token does not have access to the specified model | Contact the administrator to grant access to that model |
| — | This channel has been disabled | The channel specified in the request has been disabled by the administrator | Contact the administrator to confirm the channel status; or do not specify a channel in the request |
| — | No permission to access this group | The token does not have permission to access the group used in the request | Contact the administrator to grant the token access to that group |
| — | Unable to parse client IP address | The platform cannot parse the requester's IP address | Check the network environment; if accessing through a proxy, confirm the proxy header configuration is correct |
| — | Your IP is not in the token's allowed access list | The token has an IP whitelist configured, and the current request IP is not in the list | Contact the administrator to add the current IP to the token's IP whitelist |
| — | User has been banned | The user associated with the token has been banned by the administrator | Contact the administrator to unban the user account |
| — | Regular users are not allowed to specify a channel | Regular users are not allowed to specify a channel in the request | Remove the channel specification parameter from the request; or contact the administrator to elevate user permissions |
| — | Token has no available valid groups | All groups bound to the token have been deleted or have no rate configured | Contact the administrator to bind valid groups to the token |
| — | user group is empty | The user group in the token's group policy is empty | Contact the administrator to configure valid groups for the user |
| — | invalid subject type: <type> | The subject type in the group policy is invalid | Contact the administrator to check the subject type configuration of the group policy |
| — | This model is a domestic model, your account only allows access to international models | The token's account only allows access to international models, but the requested model is a domestic model | Switch to an international model; or contact the administrator to adjust the account's model access scope |
| — | This model is an international model, your account only allows access to domestic models | The token's account only allows access to domestic models, but the requested model is an international model | Switch to a domestic model; or contact the administrator to adjust the account's model access scope |
HTTP 404 — Not Found
The requested API path does not exist, or no available channel is configured for the specified model under the current group.
| code | message | Cause | Solution |
|---|---|---|---|
| — | Invalid URL (<Method> <Path>) | The requested URL path is not in the platform's supported API list | Check that the request URL path and HTTP method are correct, and adjust according to the API documentation |
model_not_found | No available channel for model <model> under group <group> (distributor) | No available channel is configured for this model under the specified group | Contact the administrator to add a channel that supports this model to the group, or switch to a configured model |
model_not_found | Failed to get available channel for model <model> under group <group> (distributor): <error> | An error occurred when the platform was querying available channels | Retry later; if the issue persists, contact the administrator to check the group and channel configuration |
model_not_found | None of the token's groups (<groups>) support model <model> | None of the groups bound to the token have this model configured | Contact the administrator to add the model to a group, or bind a group that supports the model to the token |
model_not_found | user group is empty | The user group is empty during multi-group dynamic selection | Contact the administrator to configure valid groups for the user |
HTTP 413 — Request Body Too Large
The request body exceeds the maximum length allowed by the platform.
| code | message | Cause | Solution |
|---|---|---|---|
read_request_body_failed | http: request body too large or similar IO error | The request body size exceeds the platform limit | Reduce the request body size, e.g., shorten the input text, reduce the number of images, or reduce attachment size, then retry |
HTTP 429 — Rate Limit
The request frequency exceeds the limit. Reduce the request rate.
| code | message | Cause | Solution |
|---|---|---|---|
rate_limit_exceeded | You have reached the request count limit: max <Y> requests per <X> minutes | The number of successful requests per unit time exceeded the token's configured RPM limit (V1) | Reduce the request frequency and retry after the limit window (X minutes) ends |
rate_limit_exceeded | You have reached the total request count limit: max <Y> requests per <X> minutes, including failed requests. Please check if your requests are correct | The total number of requests (including failed ones) per unit time exceeded the limit (V1) | Reduce the request frequency; also check whether the request parameters are correct to reduce failed requests and avoid consuming quota |
rate_limit_exceeded | enterprise RPM limit exceeded (model: <model>, limit: <N>/<M>min) | Enterprise-level model RPM rate limit triggered (V2) | Reduce the request frequency and retry after the limit window ends |
rate_limit_exceeded | enterprise TPM limit exceeded (model: <model>, limit: <N>/<M>min) | Enterprise-level model TPM rate limit triggered (V2) | Reduce the request frequency or reduce the token count per request, and retry after the limit window ends |
rate_limit_exceeded | user RPM limit exceeded (model: <model>, limit: <N>/<M>min) | User-level model RPM rate limit triggered (V2) | Reduce the request frequency and retry after the limit window ends |
rate_limit_exceeded | user TPM limit exceeded (model: <model>, limit: <N>/<M>min) | User-level model TPM rate limit triggered (V2) | Reduce the request frequency or reduce the token count per request, and retry after the limit window ends |
HTTP 500 — Internal Server Error
An error occurred within the platform while processing the request. In most cases, retrying will resolve the issue.
| code | message | Cause | Solution |
|---|---|---|---|
count_token_failed | Token count failed: <underlying error>, e.g., Token count failed: failed to count tokens | An internal error occurred when the platform was counting request tokens | Retry later; if the issue persists, contact the administrator |
gen_relay_info_failed | Failed to generate Relay info: <underlying error>, e.g., Failed to generate Relay info: channel not found | An error occurred when the platform was generating relay metadata | Retry later; if the issue persists, contact the administrator |
get_channel_failed | Failed to get channel: <underlying error>, e.g., Failed to get channel: channel is nil | An error occurred when the platform was retrieving an available channel | Retry later; if the issue persists, contact the administrator to check the channel configuration |
do_request_failed | Request execution failed: <underlying error>, e.g., Request execution failed: dial tcp: connection refused | A network or connection error occurred when the platform was making a request to the downstream | Retry later; if the issue persists, contact the administrator |
invalid_api_type | Invalid API type | The API type configured for the channel is invalid | Contact the administrator to check the channel's API type configuration |
json_marshal_failed | JSON serialization failed: <underlying error>, e.g., JSON serialization failed: json: unsupported type: chan int | An error occurred when the platform was serializing the request body | Retry later; if the issue persists, contact the administrator |
convert_request_failed | Request conversion failed: <underlying error>, e.g., Request conversion failed: unsupported model format | An error occurred when the platform was converting the request to the upstream format | Retry later; if the issue persists, contact the administrator |
bad_request_body | Request body format error: <underlying error>, e.g., Request body format error: invalid character 'x' looking for beginning of value | An error occurred when the platform was parsing the request body for a specific channel (e.g., Volcano TTS, AWS) | Check that the request body conforms to that channel's parameter specification and retry |
query_data_error | Data query error: <underlying error>, e.g., Data query error: record not found | An error occurred while querying data during the pre-deduction step | Retry later; if the issue persists, contact the administrator |
update_data_error | Data update error: <underlying error>, e.g., Data update error: Error 1062: Duplicate entry | An error occurred when the platform was updating data | Retry later; if the issue persists, contact the administrator |
channel:no_available_key | Channel has no available keys | All keys under the channel are unavailable (disabled or exhausted) | Contact the administrator to check the channel key configuration and confirm that keys are valid and not all disabled |
channel:header_override_invalid | Channel header override config invalid: invalid character 'x' looking for beginning of value, etc. | The channel's header override configuration JSON is malformed | Contact the administrator to check whether the channel's "header override" configuration is valid JSON |
channel:model_mapped_error | Model mapping error: <underlying error>, e.g., Model mapping error: target model not found in mapping | The channel model mapping configuration is incorrect | Contact the administrator to check the channel's model mapping configuration |
channel:aws_client_error | AWS client error | The AWS channel client failed to initialize or call | Contact the administrator to check the AWS channel configuration (keys, region, etc.) |
channel:invalid_key | Channel key invalid | The key configured for the channel is invalid | Contact the administrator to check whether the channel key is correct and valid |
aws_invoke_error | AWS invocation error | An error occurred when calling the AWS service | Retry later; if the issue persists, contact the administrator to check the AWS channel configuration |
prompt_blocked | Input blocked | The input content was blocked by the upstream safety policy | Modify the input content and retry; if you confirm the content is compliant but it keeps being blocked, contact the administrator |
empty_response | Empty response | The upstream returned an empty response | Retry later; if the issue persists, contact the administrator |
| — | rate_limit_check_failed | An internal error occurred during the rate limit check | Retry later; if the issue persists, contact the administrator |
| — | Enterprise information error | The enterprise information associated with the token is abnormal | Contact the administrator to confirm the enterprise configuration is normal |
| — | record not found, user cache incomplete: missing Setting field, etc. | An error occurred while retrieving the user cache (e.g., user has been soft-deleted, cache data is incomplete) | Retry later; if the issue persists, contact the administrator |
HTTP 501 — Not Implemented
The requested API has not been implemented.
| code | message | Cause | Solution |
|---|---|---|---|
api_not_implemented | API not implemented | The requested API path exists but has not been implemented yet | Confirm the API path is correct; the API may not be online yet, contact the administrator to confirm |
HTTP 503 — Service Unavailable
No available channel to handle the request, usually due to channel configuration or capacity issues.
| code | message | Cause | Solution |
|---|---|---|---|
| — | No available Kling channel | There is no available Kling channel under the current group | Contact the administrator to add an available Kling channel to the group |
| — | No available Kling channel (channel <name> is not enabled or does not exist) | The Kling fixed channel is not enabled or does not exist | Contact the administrator to check the channel configuration |
| — | No available MiniMax channel | There is no available MiniMax channel under the current group | Contact the administrator to add an available MiniMax channel to the group |
| — | No available MiniMax channel (channel <name> is not enabled or does not exist) | The MiniMax fixed channel is not enabled or does not exist | Contact the administrator to check the channel configuration |
| — | channel is nil or no keys available | An error occurred when the platform was initializing the specified channel context (channel is nil or keys are unavailable) | Contact the administrator to check whether the channel configuration is correct |
Appendix: Error Response Examples
json
{
"error": {
"code": "model_not_found",
"message": "No available channel for model happyhorse-1.0-i2v-720p under group default (distributor) (request id: 20260630102222308068043y9Cfyxgr)",
"type": "neolink_error"
}
}json
{
"error": {
"code": "TOKEN_MONTHLY_QUOTA_EXHAUSTED",
"message": "Token monthly quota exhausted",
"type": "neolink_error"
}
}json
{
"error": {
"code": "invalid_request",
"message": "Invalid request, <specific error> (request id: <id>)",
"type": "neolink_error"
}
}json
{
"error": {
"code": "rate_limit_exceeded",
"message": "enterprise RPM limit exceeded (model: gpt-4, limit: 100/1min) (request id: <id>)",
"type": "neolink_error"
}
}