/v1/chat/completions) or the Responses protocol (/v1/responses), error responses follow the unified structure below.{"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 | 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. |
type field is uniformly set to gateway_error, and the source field is not returned.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.{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 | 400001CodeInvalidRequest | The request is invalid. Please check whether the request body, required fields, and request format are correct. |
400 | 400002CodeInvalidParameter | The request parameter is invalid or missing. Please check whether the value of this parameter is correct. |
400 | 400003CodeInputTooLong | The number of input tokens exceeds the model's context limit. |
400 | 400004CodeModelNotFound | 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 | 400005CodeUnsupportedModel | The current model does not support the requested protocol or capability. Please switch the access protocol/capability or view the console invocation example. |
400 | 400006CodeUnsupportedFormat | 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 | 401006CodeInvalidEndpoint | 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 | 401001CodeUnauthorized | The request does not carry authentication information, or the authentication method cannot be recognized. Please check whether the API Key is correct. |
401 | 401002CodeInvalidAPIKey | The API Key does not exist or the signature verification failed. Please check whether the API Key is correct. |
401 | 401003CodeAPIKeyExpired | The API Key has expired. Please check or regenerate the API Key. |
401 | 401004CodeAPIKeyDisabled | The API Key has been disabled. Please check the API Key status. |
401 | 401005CodeSignatureInvalid | The CAM or custom signature verification failed. Please check the signature algorithm, key, and request time. |
402 | 401007CodeEndpointNoFreePackage | 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 | 401008CodeEndpointFreeQuotaExhausted | 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 | 403004CodeInsufficientBalance | 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 | 403001CodePermissionDenied | The package is disabled or has no call permissions. Go to the console to check the package status. |
403 | 403002CodeModelAccessDenied | 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 | 403003CodeAccountBlocked | The account to which the API Key belongs has been disabled. Contact Tencent Cloud after-sales service to obtain support. |
403 | 403005CodeIPNotAllowed | 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 | 403006CodeToolUnavailable | The requested tool is unavailable or not subscribed. Go to the console to check the subscription status of the tool. |
410 | 410001CodeSessionExpired | The provider bound to the session has been taken offline. Use a new X-Session-ID to re-establish the session. |
413 | 413001CodeRequestBodyTooLarge | The request body is too large, exceeding the maximum allowed bytes. Reduce the request body size and try again. |
429 | 429001CodeRateLimitExceeded | 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 | 429002CodeRPMLimitExceeded | 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 | 429003CodeTPMLimitExceeded | 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 | 429004CodeTPDLimitExceeded | 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 | 429005CodeConcurrencyLimitExceeded | 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 | 429006CodeUpstreamRateLimitExceeded | The current model service is busy or has reached its capacity limit. Reduce the request frequency and try again later. |
451 | 451001CodeContentFiltered | The input or output content triggered a security policy. Adjust the content and try again. |
499 | 499001CodeRequestCanceled | The client has actively disconnected. |
500 | 500001CodeInternalError | An unknown error occurred. Please try again. If it fails multiple times, contact platform after-sales service for assistance in troubleshooting. |
502 | 502001CodeUpstreamError | 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 | 503001CodeServiceUnavailable | The service is temporarily unavailable. Please try again. If it fails multiple times, contact platform after-sales service for assistance in troubleshooting. |
504 | 504001CodeGatewayTimeout | The upstream response timed out. Please try again. If it fails multiple times, contact platform after-sales service for assistance in troubleshooting. |
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.{"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"}}
Authorization: Bearer <your-api-key> is correct, expired, or disabled. You can verify this on the API Key management page.{"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"}}
messages and model, are complete and whether their values are valid.{"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"}}
model field is available on the platform. You can view the available service IDs in the console's online inference service list./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"}}
message_zh. In this example, temperature must be within the range of [0.0, 2.0].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"}}
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.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"}}
request_id./v1/messages) to connect to TokenHub, error responses follow the official Anthropic format.{"type": "error","error": {"type": "<Error type>","message": "<Error description>","reqid": "<Request unique identifier>"}}
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 |
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. |
{"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"}}
code or message_zh. Determine the general error category based on type, and troubleshoot or submit a ticket with the reqid.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. |
Apakah halaman ini membantu?
Anda juga dapat Menghubungi Penjualan atau Mengirimkan Tiket untuk meminta bantuan.
masukan