开始使用通用返回码

通用返回码

所有业务接口统一返回 HTTP 200，通过响应体中的 Error.Code 区分成功与失败。以下为所有接口可能返回的通用错误码，各接口特有的业务错误码请参见对应接口文档。

ℹ️

Tencent eSign Open API 采用统一 HTTP 200 的响应模式。即使业务逻辑出错（如参数校验失败、资源不存在），HTTP 状态码仍为 200，错误信息通过 Response.Error.Code 和 Response.Error.Message 返回。

通用错误码

所有接口均可能返回以下错误码
错误码说明
INVALID_REQUEST请求参数错误，检查必填字段和字段格式
UNAUTHORIZED未认证或认证失败
FORBIDDEN无权限访问该资源
NOT_FOUND资源不存在，检查 ID 是否正确
INTERNAL_ERROR服务器内部错误，请联系技术支持并提供 RequestId
SERVICE_UNAVAILABLE服务暂不可用，请稍后重试
OPERATION_TIMEOUT操作超时，请稍后重试
OPERATION_FREQUENT操作过于频繁，请降低调用频率

认证层错误码

认证中间件在验证 Bearer Token 时可能返回以下错误（遵循 OAuth 2.0 / RFC 6750 规范）

认证层错误不使用 HTTP 200，而是按照 OAuth 规范返回对应的 HTTP 状态码，且响应格式与业务接口不同：

{
  "error": "invalid_token",
  "error_description": "token is expired"
}
HTTP 状态码错误码说明
401invalid_tokenBearer Token 无效、已过期或已被吊销
403insufficient_scopeToken 的权限范围不足以访问当前资源

Open API 业务错误码

调用 Open API 接口时可能返回的公共业务错误码
错误码说明
OPENAPI.OPERATOR_USER_ID_REQUIRED缺少 X-Operator-User-Id 请求头
OPENAPI.OPERATOR_USER_NOT_FOUNDX-Operator-User-Id 对应的用户不存在或不在当前空间
FILE.INVALID文件格式非法
FILE.TOO_LARGE文件大小超出限制

错误处理建议

  1. INVALID_REQUEST — 检查请求参数是否完整且格式正确，参考接口文档中的字段说明
  2. UNAUTHORIZED / invalid_token — access_token 可能已过期，重新调用 OAuth Token 接口获取
  3. FORBIDDEN / insufficient_scope — 确认应用是否有权限访问目标资源，检查 scope 配置
  4. NOT_FOUND — 确认资源 ID 是否正确，资源是否已被删除
  5. OPERATION_FREQUENT — 实现退避重试机制，建议使用指数退避策略
  6. INTERNAL_ERROR — 记录响应中的 RequestId 后联系技术支持
  7. OPENAPI.OPERATOR_USER_ID_REQUIRED — 添加 X-Operator-User-Id 请求头，值为操作人的用户 ID
响应报文场景说明