API 参考

账号

查询账号计费操作

查看当前工作区的报价，以及账号创建、删除和退款处理结果。

GEThttps://api.unifyport.ai/v1/account-operations/{operation_id}

支持的渠道

all

调用前准备

在服务端使用资源所属工作区的 X-Api-Key。运行示例前替换所有占位符。

使用目标工作区的 API Key。余额模式账号按 30 天以 USD 计费；钱包余额和充值请在 Dashboard 查看。

请求参数

请求头

X-Api-Key
string必填

工作区 API Key，工作区由该请求头解析得到。

路径参数

operation_id
string必填

来自 billing.operation_id 或删除响应的公开标识，在原工作区原样复用。

请求体

该接口无需 JSON 请求体。

如何理解结果

保留原 operation_id。PENDING/PROCESSING 需等待，REVIEW 需核对。SUCCEEDED/FAILED 只说明本次操作，不代表授权或自动退款；退款以服务端钱包记录为准。

响应 200 OK

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "operation_id": "op_example",
    "kind": "DELETE",
    "state": "REVIEW",
    "account_id": "acc_example",
    "last_error_code": "cleanup_unconfirmed"
  }
}

响应体

operation_id
string

来自 billing.operation_id 或删除响应的公开标识，在原工作区原样复用。

kind
string

公开操作类型：QUOTE / CREATE、DELETE、COMPENSATE。

enum: QUOTE, CREATE, DELETE, COMPENSATE

state
string

计费或操作状态，不证明账号已授权、在线或退款已入账。

enum: QUOTED, CONSUMED, EXPIRED, PENDING, PROCESSING, SUCCEEDED, FAILED, REVIEW

account_id
string

当前工作区的公开消息账号标识。

last_error_code
string

安全公开结果码，缺失不代表成功。

响应

200

200 OK

请求成功，响应体示例如上。

400

请求错误

请求体、路径或参数不合法。

401

未授权

X-Api-Key 请求头缺失或无效。

403

禁止访问

请求已识别，但不允许执行该操作。

404

未找到

未找到请求的资源；请结合 error.code 和当前操作核对。

409

冲突

当前操作与已有的渠道账号或资源冲突。

503

服务不可用

所需的后端服务暂时不可用。

失败后怎么处理

检查 HTTP 状态和 error.code/numeric_code，保存 request_id 用于排查。按原因修正参数、继续授权或检查运行态。重试发送及其他写操作前先确认上一次结果，避免重复操作。 错误码参考

结合当前操作读取 HTTP 状态、error.code 和 error.numeric_code。数字码按字符串处理。保留 request_id 排障；它不是幂等键或任务标识。

invalid_request · 10000 · 400

检查 JSON 请求体和必填字段。

触发条件: 适用于请求体非空，但 Content-Type 不是 application/json 的请求。

处理与重试: 按当前操作与渠道条件修正参数后再请求。重复提交相同的无效请求不会解决错误。

示意 JSON；message 随实际原因变化 · 400 · 10000
{
  "request_id": "req_example",
  "error": {
    "code": "invalid_request",
    "numeric_code": "10000",
    "message": "Content-Type must be application/json"
  }
}
invalid_target_workspace · 11003 · 400

工作区覆盖目标为空或格式无效。移除覆盖请求头，改用目标工作区所属的 API Key。

触发条件: 适用于携带 X-Workspace-Id 工作区覆盖请求头的请求。

处理与重试: 按当前操作与渠道条件修正参数后再请求。重复提交相同的无效请求不会解决错误。

示意 JSON；message 随实际原因变化 · 400 · 11003
{
  "request_id": "req_example",
  "error": {
    "code": "invalid_target_workspace",
    "numeric_code": "11003",
    "message": "Invalid target workspace"
  }
}
invalid_api_key · 11001 · 401

检查 API Key 是否正确且已启用。

处理与重试: 保留 request_id 与结构化错误码，先排查当前操作，再决定下一步。

示意 JSON；message 随实际原因变化 · 401 · 11001
{
  "request_id": "req_example",
  "error": {
    "code": "invalid_api_key",
    "numeric_code": "11001",
    "message": "Invalid API key"
  }
}
missing_api_key · 11000 · 401

请添加 X-Api-Key 请求头。

处理与重试: 保留 request_id 与结构化错误码，先排查当前操作，再决定下一步。

示例 · 401 · 11000
{
  "request_id": "req_xxx",
  "error": {
    "code": "missing_api_key",
    "numeric_code": "11000",
    "message": "Missing X-Api-Key header"
  }
}
workspace_override_forbidden · 11002 · 403

请求尝试使用此 API Key 无权使用的工作区覆盖。移除覆盖请求头，改用目标工作区所属的 API Key。

触发条件: 适用于携带 X-Workspace-Id 工作区覆盖请求头的请求。

处理与重试: 保留 request_id 与结构化错误码，先排查当前操作，再决定下一步。

示意 JSON；message 随实际原因变化 · 403 · 11002
{
  "request_id": "req_example",
  "error": {
    "code": "workspace_override_forbidden",
    "numeric_code": "11002",
    "message": "Workspace override is not allowed"
  }
}
account_operation_not_found · 20029 · 404

操作不存在或不属于当前工作区，请核对原 operation_id 与 API Key 作用域。

处理与重试: 核对目标标识、资源归属与当前工作区。不要把已确认缺失或无法访问的目标当作临时服务故障自动重试。

示意 JSON；message 随实际原因变化 · 404 · 20029
{
  "request_id": "req_example",
  "error": {
    "code": "account_operation_not_found",
    "numeric_code": "20029",
    "message": "Account operation not found"
  }
}
target_workspace_not_found · 11004 · 404

覆盖指定的工作区不存在或不可用。核对工作区归属，移除覆盖请求头并使用目标工作区 API Key；重复请求不会增加访问权限。

触发条件: 适用于携带 X-Workspace-Id 工作区覆盖请求头的请求。

处理与重试: 核对目标标识、资源归属与当前工作区。不要把已确认缺失或无法访问的目标当作临时服务故障自动重试。

示意 JSON；message 随实际原因变化 · 404 · 11004
{
  "request_id": "req_example",
  "error": {
    "code": "target_workspace_not_found",
    "numeric_code": "11004",
    "message": "Target workspace not found"
  }
}
wallet_workspace_disabled · 20022 · 409

新余额消费已关闭；不代表既有账号操作已取消。

处理与重试: 保留 request_id 与结构化错误码，先排查当前操作，再决定下一步。

示意 JSON；message 随实际原因变化 · 409 · 20022
{
  "request_id": "req_example",
  "error": {
    "code": "wallet_workspace_disabled",
    "numeric_code": "20022",
    "message": "New wallet purchases are disabled"
  }
}
wallet_unavailable · 20028 · 503

钱包数据或配置暂不可用；写入失败可能结果未知，请核对原操作。

处理与重试: 保留 request_id，核对目标标识与账号访问范围。查明原因后再重试查询；查询失败不等于结果为空或资源不存在。

示意 JSON；message 随实际原因变化 · 503 · 20028
{
  "request_id": "req_example",
  "error": {
    "code": "wallet_unavailable",
    "numeric_code": "20028",
    "message": "Wallet service is unavailable"
  }
}