API 参考

工作区

更新当前工作区

更新工作区的 name 和 status，这两个字段均为必填；status 仅接受 active / inactive，inactive 会使该工作区全部 API Key 无法鉴权。省略 metadata 保留现值，传 metadata={} 表示清空，不能传 null。 is_beta 是默认关闭的只读工作区标识。需联系平台开通，不能通过 PATCH 或 metadata 自行修改。

PATCHhttps://api.unifyport.ai/v1/workspace

支持的渠道

all

调用前准备

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

请求参数

请求头

X-Api-Key
string必填

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

Content-Type
string必填

发送 JSON 请求体时使用 application/json。

请求体

name
string必填

工作区显示名。

minLength: 1

status
string必填

工作区状态：active 或 inactive。inactive 会使该工作区全部 API Key 无法鉴权。

enum: active, inactive

metadata
object

工作区元数据。PATCH 时省略表示保留，传 {} 表示清空，null 非法。

如何理解结果

按本接口的响应字段和 HTTP 状态判断结果，再通过相关操作选择下一步。

响应 200 OK

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "name": "Production Workspace",
    "status": "active",
    "metadata": {
      "region": "global",
      "env": "production"
    },
    "account_quota": 10,
    "account_quota_used": 1,
    "account_quota_unlimited": false,
    "is_beta": false
  }
}

响应体

is_beta
boolean

is_beta 是默认关闭的只读工作区标识。需联系平台开通，不能通过 PATCH 或 metadata 自行修改。

name
string

工作区显示名。

status
string

工作区状态：active 或 inactive；inactive 时全部 API Key 无法鉴权。

enum: active, inactive

metadata
object

存储在工作区上的自有环境标签。

account_quota
integer

当前生效的只读账号总容量，包含免费额度和有效期内的付费额度，不扣除已用数量；已到期的付费额度不计入。

format: uint64

account_quota_used
integer

当前已占用的只读账号额度，账号创建后即占用，删除后释放；待授权、停止或断线的账号仍计入。付费额度到期后，已用额度可能超过 account_quota，按实际已用值返回。

format: uint64

account_quota_unlimited
boolean

兼容保留的只读字段，当前配额模式固定返回 false；账号容量以 account_quota 为准。

响应

200

200 OK

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

400

请求错误

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

401

未授权

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

403

禁止访问

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

404

未找到

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

500

服务端错误

服务端遇到了未预期的错误。

失败后怎么处理

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

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

invalid_request · 10000 · 400

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

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

示意 JSON；message 随实际原因变化 · 400 · 10000
{
  "request_id": "req_example",
  "error": {
    "code": "invalid_request",
    "numeric_code": "10000",
    "message": "Invalid request parameters"
  }
}
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"
  }
}
update_workspace_failed · 41001 · 400

操作被拒绝，请检查请求并保留 request_id 排查。

处理与重试: 先读取资源当前状态，确认上一次改动结果，再决定是否重试。保留 request_id；结果未知时不要自动重复写入。

示意 JSON；message 随实际原因变化 · 400 · 41001
{
  "request_id": "req_example",
  "error": {
    "code": "update_workspace_failed",
    "numeric_code": "41001",
    "message": "Failed to update 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"
  }
}
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"
  }
}