tencent cloud

API Error Codes

Download
Mode fokus
Ukuran font
Terakhir diperbarui: 2026-08-14 18:39:39
Diterjemahkan oleh AI
This document helps you understand the error response format of the TokenHub API, enabling you to quickly locate and resolve calling issues.
TokenHub uses the OpenAI-compatible protocol by default, and is also compatible with the Anthropic Messages and OpenAI Responses protocols. When an API call fails, it returns an HTTP status code other than 2xx and a JSON-formatted response body, which includes error descriptions in both Chinese and English to facilitate troubleshooting.

I. OpenAI/Responses Compatibility Protocol (Standard Link)

When you access the service using the OpenAI-compatible protocol (/v1/chat/completions) or the Responses protocol (/v1/responses), error responses follow the unified structure below.

1.1 Error Response Structure

{
"error": {
"message": "<English error description>",
"message_zh": "<Chinese error description>",
"code": "<Business error code>",
"type": "<Error type>",
"source": "client | gateway | upstream",
"upstream_code": "<Upstream error code, returned only for upstream errors>",
"upstream_status": "<Upstream HTTP status code, returned only for upstream errors>",
"request_id": "<Request unique identifier>"
}
}
Field description:
Field
Type
Description
message
string
Error description in English.
message_zh
string
Chinese error description, which corresponds one-to-one with message for direct display in Chinese scenarios.
code
string
Platform business error code (for example, 401002), used for pinpointing issues; may be returned as an integer in rate-limiting scenarios.
type
string
Error type, used by programs to determine the error category. Errors that cause early termination in the request chain (such as authentication and parameter validation) are uniformly categorized as gateway_error.
source
string
Source of the error: client (requesting end), gateway (gateway), upstream (upstream service). This field is returned only for errors at the Handler layer.
upstream_code
string
Original error code from the upstream service, which appears only when source=upstream.
upstream_status
number
HTTP status code from the upstream service, which appears only when source=upstream.
request_id
string
Unique identifier of the request, used for troubleshooting and submitting tickets.
Attention:
For errors intercepted early in the request chain (such as authentication failure or invalid parameters), the type field is uniformly set to gateway_error, and the source field is not returned.
In rate limiting (429) scenarios, the code field may be returned as an integer and include the Retry-After response header (unit: seconds). When parsing the error.code field, the client should handle both string and numeric types.

1.2 Business Error Code Quick Reference

The following table lists all business error codes defined by maas-gateway, along with their corresponding HTTP status codes, error causes, and handling methods. The {xxx} placeholders in the content are dynamically populated at runtime with specific values (such as parameter names, model IDs, quota amounts, and so on).
HTTP
Error Code
Error Cause and Resolution
400
400001
CodeInvalidRequest
The request is invalid. Please check whether the request body, required fields, and request format are correct.
400
400002
CodeInvalidParameter
The request parameter is invalid or missing. Please check whether the value of this parameter is correct.
400
400003
CodeInputTooLong
The number of input tokens exceeds the model's context limit.
400
400004
CodeModelNotFound
The model or service ID in the request does not exist. Please check whether the service ID is correct. The service ID can be viewed in the online inference service list in the console.
400
400005
CodeUnsupportedModel
The current model does not support the requested protocol or capability. Please switch the access protocol/capability or view the console invocation example.
400
400006
CodeUnsupportedFormat
The current model does not support the requested response_format or output format. Please check the parameter support scope in the console or product documentation.
400
401006
CodeInvalidEndpoint
The input service ID does not exist, or the model does not match the service. Please confirm the service ID in the online inference service list in the console.
401
401001
CodeUnauthorized
The request does not carry authentication information, or the authentication method cannot be recognized. Please check whether the API Key is correct.
401
401002
CodeInvalidAPIKey
The API Key does not exist or the signature verification failed. Please check whether the API Key is correct.
401
401003
CodeAPIKeyExpired
The API Key has expired. Please check or regenerate the API Key.
401
401004
CodeAPIKeyDisabled
The API Key has been disabled. Please check the API Key status.
401
401005
CodeSignatureInvalid
The CAM or custom signature verification failed. Please check the signature algorithm, key, and request time.
402
401007
CodeEndpointNoFreePackage
The service has no available free trial quota and postpaid is not enabled, so it cannot be accessed normally. Go to Console > Online Inference Service to enable postpaid.
402
401008
CodeEndpointFreeQuotaExhausted
The free trial quota for the service has been exhausted and postpaid is not enabled, so it cannot be accessed normally. Go to Console > Online Inference Service to enable postpaid.
402
403004
CodeInsufficientBalance
The account to which the API Key belongs has an overdue payment, and the accessed service ID has been isolated. Recharge your account and then re-enable the service in the console.
403
403001
CodePermissionDenied
The package is disabled or has no call permissions. Go to the console to check the package status.
403
403002
CodeModelAccessDenied
The current API Key does not have permission to access the model. Go to the API Key management page in the console to check the accessible scope of the Key.
403
403003
CodeAccountBlocked
The account to which the API Key belongs has been disabled. Contact Tencent Cloud after-sales service to obtain support.
403
403005
CodeIPNotAllowed
The source IP address of the request is not in the allowlist of the API Key. Go to the API Key management page in the console to check whether the IP address is within the allowlist scope.
403
403006
CodeToolUnavailable
The requested tool is unavailable or not subscribed. Go to the console to check the subscription status of the tool.
410
410001
CodeSessionExpired
The provider bound to the session has been taken offline. Use a new X-Session-ID to re-establish the session.
413
413001
CodeRequestBodyTooLarge
The request body is too large, exceeding the maximum allowed bytes. Reduce the request body size and try again.
429
429001
CodeRateLimitExceeded
The request rate exceeds the current model threshold. Reduce the access frequency or contact Tencent Cloud after-sales service to apply for a higher quota.
429
429002
CodeRPMLimitExceeded
The request rate exceeds the current model RPM (requests per minute) threshold. Reduce the access frequency or contact Tencent Cloud after-sales service to apply for a higher quota.
429
429003
CodeTPMLimitExceeded
Token usage exceeds the current model TPM (tokens per minute) threshold. Reduce the access frequency or contact Tencent Cloud after-sales service to apply for a higher quota.
429
429004
CodeTPDLimitExceeded
Token usage exceeds the current model TPD (tokens per day) threshold. Reduce the access frequency or contact Tencent Cloud after-sales service to apply for a higher quota.
429
429005
CodeConcurrencyLimitExceeded
The request exceeds the current model's rate limiting threshold. Reduce the access frequency or contact Tencent Cloud after-sales service to apply for a higher quota.
429
429006
CodeUpstreamRateLimitExceeded
The current model service is busy or has reached its capacity limit. Reduce the request frequency and try again later.
451
451001
CodeContentFiltered
The input or output content triggered a security policy. Adjust the content and try again.
499
499001
CodeRequestCanceled
The client has actively disconnected.
500
500001
CodeInternalError
An unknown error occurred. Please try again. If it fails multiple times, contact platform after-sales service for assistance in troubleshooting.
502
502001
CodeUpstreamError
The upstream model service is abnormal or unreachable. Please try again. If it fails multiple times, contact platform after-sales service for assistance in troubleshooting.
503
503001
CodeServiceUnavailable
The service is temporarily unavailable. Please try again. If it fails multiple times, contact platform after-sales service for assistance in troubleshooting.
504
504001
CodeGatewayTimeout
The upstream response timed out. Please try again. If it fails multiple times, contact platform after-sales service for assistance in troubleshooting.

1.3 Error Response Example

The following examples demonstrate the response formats for various errors and can serve as a reference for client-side parsing and troubleshooting. Examples A through D are responses triggered by actual API calls (the request_id is the actual returned value). Examples E and F are constructed in the same format to illustrate the field characteristics of rate limiting and upstream errors.

Example A: Invalid API Key (HTTP 401)

{
"error": {
"message": "The API Key does not exist or signature verification failed. Please check whether the API Key is correct. See: https://console.tencentcloud.com/tokenhub/apikey",
"message_zh": "The API Key does not exist or signature verification failed. Please check whether the API Key is correct. For details, see: https://console.tencentcloud.com/tokenhub/apikey",
"code": "401002",
"type": "gateway_error",
"request_id": "7e6dc7d0-a8d7-4993-a74d-f6cd24b33925"
}
}
Troubleshooting suggestion: Check whether the API Key in the request header Authorization: Bearer <your-api-key> is correct, expired, or disabled. You can verify this on the API Key management page.

Example B: Missing Parameters (HTTP 400)

{
"error": {
"message": "The request parameter messages is invalid or missing. Please check the value of this parameter.",
"message_zh": "The request parameter 'messages' is invalid or missing. Please check whether its value is correct.",
"code": "400002",
"type": "gateway_error",
"request_id": "5fcdcb74-bd31-4bc6-b265-1389cea2d915"
}
}
Troubleshooting suggestion: Check whether the required fields in the request body, such as messages and model, are complete and whether their values are valid.

Example C: Model Not Found (HTTP 400)

{
"error": {
"message": "The model or service ID gpt-9-turbo does not exist. Please check whether the service ID is correct. Service IDs are available in the Online Inference Service list in the console. See: https://www.tencentcloud.com/document/product/1823/130079?from_cn_redirect=1",
"message_zh": "The model or service ID 'gpt-9-turbo' in the request does not exist. Please check whether the service ID is correct. The service ID can be viewed in the online inference service list in the console. For details, see: https://www.tencentcloud.com/document/product/1823/130079?from_cn_redirect=1",
"code": "400004",
"type": "gateway_error",
"request_id": "7a948a0f-740f-4d37-846f-0b500c3f1c48"
}
}
Troubleshooting suggestion: Confirm that the model or service ID entered in the model field is available on the platform. You can view the available service IDs in the console's online inference service list.

Example D: Invalid Responses Protocol Parameter (HTTP 400)

When the Responses protocol (/v1/responses) fails validation at the Handler layer, the source field is additionally returned:
{
"error": {
"message": "The request is invalid: temperature must be [0.0, 2.0]. Please check the request body, required fields, and request format.",
"message_zh": "The request is invalid: temperature must be [0.0, 2.0]. Please check whether the request body, required fields, and request format are correct.",
"code": "400001",
"type": "invalid_request_error",
"source": "client",
"request_id": "d4924d12-a56f-4a51-94f4-dab3608dd6c4"
}
}
Troubleshooting suggestion: Correct the parameter values as indicated by message_zh. In this example, temperature must be within the range of [0.0, 2.0].

Example E: Rate Limit Triggered (HTTP 429)

In a rate limiting response, the code field is returned as an integer and includes the Retry-After response header (unit: seconds):
{
"error": {
"code": 429001,
"message": "The request rate exceeds the current model deepseek-v4-flash-202605 limit 60. Please reduce the request frequency or contact Tencent Cloud support to request a higher limit.",
"message_zh": "The request rate exceeds the threshold of 60 for the current model 'deepseek-v4-flash-202605'. Please reduce the access frequency or contact Tencent Cloud after-sales service to apply for a higher quota.",
"request_id": "req-16c2ae01"
}
}
Troubleshooting suggestion: The message indicates which rate limit dimension has been exceeded (rpm/tpm/tpd/concurrency). Retry with backoff according to the Retry-After response header, reduce the call frequency, or contact the platform to request a quota increase.

Example F: Upstream Service Error (HTTP 502)

When the upstream model service returns an error or is unreachable, source is set to upstream and the upstream status is forwarded:
{
"error": {
"message": "The upstream model service is abnormal or unreachable. Please try again. If the issue persists, contact platform support for troubleshooting.",
"message_zh": "The upstream model service is abnormal or unreachable. Please retry. If failures persist after multiple attempts, contact the platform's after-sales service for assistance with troubleshooting.",
"code": "502001",
"type": "upstream_error",
"source": "upstream",
"upstream_status": 502,
"request_id": "req-7d2c4a11"
}
}
Troubleshooting suggestion: The upstream model service is temporarily abnormal. Retry using an exponential backoff policy. If failures persist, submit a ticket with the request_id.

II. Anthropic-Compatible Protocol

If you use the Anthropic Messages protocol (/v1/messages) to connect to TokenHub, error responses follow the official Anthropic format.

2.1 Error Response Structure

{
"type": "error",
"error": {
"type": "<Error type>",
"message": "<Error description>",
"reqid": "<Request unique identifier>"
}
}

2.2 Differences from the Standard Format

Comparison Item
OpenAI / Responses Protocol
Anthropic Protocol
Outer structure
Only the error object
The outer layer includes an additional "type": "error".
Business code
Returns the code field.
Does not return code
Description
Returns the message_zh field.
Does not return the message_zh field (only the English message field).
Request ID field name
request_id
reqid
Error source
Returns the source field.
Does not return source

2.3 Anthropic Protocol Error Types

Error type
Description
invalid_request_error
Invalid request parameter.
authentication_error
Authentication Failure
permission_error
Insufficient Permissions
not_found_error
The resource does not exist.
rate_limit_error
Rate Limiting
overloaded_error
Service Overload
api_error
An internal server error occurs.

2.4 Example: Invalid API Key (HTTP 401)

The following is an Anthropic protocol error response triggered by a real call:
{
"type": "error",
"error": {
"type": "authentication_error",
"message": "The API Key does not exist or signature verification failed. Please check whether the API Key is correct. See: https://console.tencentcloud.com/tokenhub/apikey",
"reqid": "e556c76e-acf8-46ef-88f4-8395f3cd6ffc"
}
}
Troubleshooting suggestion: The Anthropic protocol does not return code or message_zh. Determine the general error category based on type, and troubleshoot or submit a ticket with the reqid.

III. Obtaining Help and Submitting Tickets

If you still cannot resolve the issue after troubleshooting, you can submit a ticket to contact Tencent Cloud technical support for assistance.
When submitting a ticket, provide the following information:
Required Information
Description
Request ID
The request_id (OpenAI / Responses protocol) or reqid (Anthropic protocol) in the error response is the only index for backend troubleshooting. You must provide it in the ticket. Missing this value will significantly increase the time to locate the issue.
Request Time
The approximate time point when the error occurred.
Request parameters.
The name of the model used, the endpoint, and so on.
Error Response
The complete error response JSON.

Bantuan dan Dukungan

Apakah halaman ini membantu?

masukan