Error Codes

All business API endpoints return HTTP 200 uniformly. Success or failure is indicated by the Error.Code field in the response body. Below are common error codes that may be returned by all endpoints. For endpoint-specific error codes, refer to the respective API documentation.

ℹ️

Tencent eSign Open API uses a unified HTTP 200 response pattern. Even when a business error occurs (e.g., parameter validation failure, resource not found), the HTTP status code is still 200. Error information is returned through Response.Error.Code and Response.Error.Message.

Common Error Codes

The following error codes may be returned by all endpoints

Error Code	Description
`INVALID_REQUEST`	Invalid request parameters — check required fields and field formats
`UNAUTHORIZED`	Unauthenticated or authentication failed
`FORBIDDEN`	No permission to access this resource
`NOT_FOUND`	Resource not found — verify the ID is correct
`INTERNAL_ERROR`	Internal server error — contact support with the RequestId
`SERVICE_UNAVAILABLE`	Service temporarily unavailable, please retry later
`OPERATION_TIMEOUT`	Operation timed out, please retry later
`OPERATION_FREQUENT`	Too many requests — reduce call frequency

Authentication Error Codes

The authentication middleware may return the following errors when validating Bearer Tokens (per OAuth 2.0 / RFC 6750)

Authentication errors do not use HTTP 200. Instead, they follow the OAuth specification and return the corresponding HTTP status code with a different response format:

{
  "error": "invalid_token",
  "error_description": "token is expired"
}

HTTP Status	Error Code	Description
401	`invalid_token`	Bearer Token is invalid, expired, or revoked
403	`insufficient_scope`	Token scope is insufficient to access the requested resource

Open API Business Error Codes

Common business error codes when calling Open API endpoints

Error Code	Description
`OPENAPI.OPERATOR_USER_ID_REQUIRED`	Missing X-Operator-User-Id request header
`OPENAPI.OPERATOR_USER_NOT_FOUND`	User specified by X-Operator-User-Id not found or not in the current space
`FILE.INVALID`	Invalid file format
`FILE.TOO_LARGE`	File size exceeds the limit

Error Handling Recommendations

INVALID_REQUEST — Verify request parameters are complete and correctly formatted, refer to the field descriptions in the API docs
UNAUTHORIZED / invalid_token — The access_token may have expired; re-call the OAuth Token endpoint
FORBIDDEN / insufficient_scope — Confirm the app has permission to access the target resource, check scope configuration
NOT_FOUND — Verify the resource ID is correct and the resource has not been deleted
OPERATION_FREQUENT — Implement a backoff retry strategy (exponential backoff recommended)
INTERNAL_ERROR — Record the RequestId from the response and contact technical support
OPENAPI.OPERATOR_USER_ID_REQUIRED — Add the X-Operator-User-Id header with the operator’s user ID

Response Format Introduction