渠道方
列出渠道区域
返回某个 provider 已开通的区域。supported 表示 provider 是否在该区域可用；allocatable 表示当前是否可在该区域绑定新账号。
https://api.unifyport.ai/v1/providers/{provider}/regions支持的渠道
调用前准备
在服务端使用资源所属工作区的 X-Api-Key。运行示例前替换所有占位符。
请求参数
请求头
X-Api-Key工作区 API Key，工作区由该请求头解析得到。
路径参数
provider用于该 providers 路由的标识符。
enum: telegram, whatsapp, line, twitter, zalo, tiktok, whatsapp-protocol, x, x_client, twitter_client
请求体
该接口无需 JSON 请求体。
如何理解结果
按本接口的响应字段和 HTTP 状态判断结果，再通过相关操作选择下一步。
响应 200 OK
{
"request_id": "<REQUEST_ID>",
"data": {
"provider": "telegram",
"regions": [
{
"region": "global",
"supported": true,
"allocatable": true
}
]
}
}
响应体
provider渠道标识。调用其他接口时原样使用 API 返回的值；此接口的返回范围见下方枚举。
enum: telegram, whatsapp, line, twitter, zalo, tiktok, whatsapp-protocol
regions[]object[]区域列表，每项包含 supported 与 allocatable 标志。
regions[]区域列表，每项包含 supported 与 allocatable 标志。
region渠道部署区域标识。
supported该渠道是否已在此区域运行。
allocatable当前是否可以在此区域分配新账号。
响应
200200 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_provider · 30000 · 400
检查 URL 中的渠道标识。
处理与重试: 按当前操作与渠道条件修正参数后再请求。重复提交相同的无效请求不会解决错误。
示意 JSON；message 随实际原因变化 · 400 · 30000
{ "request_id": "req_example", "error": { "code": "invalid_provider", "numeric_code": "30000", "message": "Invalid provider parameter" } }- 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" } }- 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" } }- list_provider_regions_failed · 30011 · 500
列出渠道区域：服务未能产生有效的查询结果。
处理与重试: 保留 request_id，核对目标标识与账号访问范围。查明原因后再重试查询；查询失败不等于结果为空或资源不存在。
示意 JSON；message 随实际原因变化 · 500 · 30011
{ "request_id": "req_example", "error": { "code": "list_provider_regions_failed", "numeric_code": "30011", "message": "Failed to list provider regions" } }