帖子与评论

回复一级评论

仅回复 TikTok 自有帖子中已确认的一级评论；其他渠道或已核实的嵌套目标返回 501 unsupported_by_provider。完整核验后可返回 404 post_not_found（39000）或 comment_not_found（39001），后者不表示已搜索全部回复。403 post_inaccessible（39005）不指明原因，也不代表不存在；核验未完成不会写入。accepted 不保证展示、送达或收到 Webhook。写入后无法确认回执返回 502 reply_post_comment_failed（39004），结果未知，不要自动重发；后续读取未找到回复不证明此前未创建。

POSThttps://api.unifyport.ai/v1/accounts/{account_id}/posts/comments/reply

支持的渠道

TikTok

调用前准备

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

参数从哪里取得

account_id: 从创建或查询账号的响应取得 data.id。账号标识属于 X-Api-Key 对应的工作区。获取账号

请求

curl -X POST "https://api.unifyport.ai/v1/accounts/{account_id}/posts/comments/reply" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"post_id":"7500000000000000101","comment_id":"7500000000000000201","text":"Thank you!"}'

请求参数

请求头

X-Api-Key

string必填

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

Content-Type

string必填

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

路径参数

account_id

string必填

用于该 accounts 路由的标识符。

请求体

post_id

string必填

渠道帖子 ID，按原值以字符串传递。TikTok 要求无前导零的正十进制整数字符串，否则返回 400 provider_invalid_request。

minLength: 1 · pattern: \S

comment_id

string

已确认一级评论的渠道 ID，按原值传递非空白字符串，不转换为数字。

minLength: 1 · pattern: \S

text

string必填

回复正文须包含非空白字符，保留原文及首尾空格。

minLength: 1 · pattern: \S

如何理解结果

accepted 仅表示受理，不保证展示、送达或产生 Webhook。写入后返回 502 reply_post_comment_failed 时结果可能未知，不要自动重发；后续查询未找到回复也不证明从未创建。

响应 200 OK

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "status": "accepted"
  }
}

响应体

status

string

accepted 仅表示已接受，不代表已展示、送达或保证收到 Webhook。

enum: accepted

comment

object

仅可靠取得本次新评论回执时提供，不保证每次都有。

id

string

渠道标识，保留非空白字符串原值，不转换为数字。

minLength: 1 · pattern: \S

post_id

string

渠道标识，保留非空白字符串原值，不转换为数字。

minLength: 1 · pattern: \S

text

string

可靠取得时保留原文，包括空字符串；未知时省略。

author

object

可用时提供的作者信息。

id

string

渠道标识，保留非空白字符串原值，不转换为数字。

minLength: 1 · pattern: \S

display_name

string

可靠取得时保留原文，包括空字符串；未知时省略。

avatar_url

string

可靠取得的非空头像 URL；未知时省略。

minLength: 1

created_at

string

可靠取得的评论创建时间，RFC3339 UTC；未知时省略，不用观察时间代替。

format: date-time

parent_comment_id

string

仅在确认父子关系后提供；缺失不证明该评论是可回复的一级评论。

minLength: 1 · pattern: \S

响应

200

200 OK

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

400

请求错误

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

401

未授权

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

403

禁止访问

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

404

未找到

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

409

冲突

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

501

渠道未实现

所选渠道尚未实现该操作。

502

上游网关错误

渠道适配器或上游渠道未能完成该操作。

失败后怎么处理

核对帖子、已确认的一级评论和错误分类。写入结果未知时保留 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"
  }
}

provider_invalid_request · 30001 · 400

检查渠道专属字段及其格式。

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

示意 JSON；message 随实际原因变化 · 400 · 30001

{
  "request_id": "req_example",
  "error": {
    "code": "provider_invalid_request",
    "numeric_code": "30001",
    "message": "Provider rejected the request"
  }
}

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"
  }
}

post_inaccessible · 39005 · 403

核对账号及本接口实际要求的目标标识。post_not_found 表示已确认帖子不存在；comment_not_found 仅表示核验后未找到目标一级评论，不代表搜索过全部回复。post_inaccessible 表示无法访问，不证明不存在，也不指明原因。保留错误，查明后再选择下一步。

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

示意 JSON；message 随实际原因变化 · 403 · 39005

{
  "request_id": "req_example",
  "error": {
    "code": "post_inaccessible",
    "numeric_code": "39005",
    "message": "Post is not accessible"
  }
}

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_not_found · 20020 · 404

核对 account_id，并使用账号所属工作区的 X-Api-Key。此工作区下未找到的账号不能用当前 Key 访问。

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

示意 JSON；message 随实际原因变化 · 404 · 20020

{
  "request_id": "req_example",
  "error": {
    "code": "account_not_found",
    "numeric_code": "20020",
    "message": "Account not found"
  }
}

comment_not_found · 39001 · 404

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

示意 JSON；message 随实际原因变化 · 404 · 39001

{
  "request_id": "req_example",
  "error": {
    "code": "comment_not_found",
    "numeric_code": "39001",
    "message": "Comment not found"
  }
}

post_not_found · 39000 · 404

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

示意 JSON；message 随实际原因变化 · 404 · 39000

{
  "request_id": "req_example",
  "error": {
    "code": "post_not_found",
    "numeric_code": "39000",
    "message": "Post 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"
  }
}

account_binding_not_found · 30006 · 409

账号尚无有效的渠道连接绑定，请检查账号状态。

处理与重试: 查询授权与运行态，再按目标状态和渠道支持选择刷新、启动或重连。连接问题本身不证明已登出；依赖连接的业务操作前确认 running。

示意 JSON；message 随实际原因变化 · 409 · 30006

{
  "request_id": "req_example",
  "error": {
    "code": "account_binding_not_found",
    "numeric_code": "30006",
    "message": "Account is not bound to an available server"
  }
}

provider_not_ready · 30009 · 409

连接尚未就绪，请检查授权及 runtime_status 后再决定是否重试。

处理与重试: 查询授权与运行态，再按目标状态和渠道支持选择刷新、启动或重连。连接问题本身不证明已登出；依赖连接的业务操作前确认 running。

示意 JSON；message 随实际原因变化 · 409 · 30009

{
  "request_id": "req_example",
  "error": {
    "code": "provider_not_ready",
    "numeric_code": "30009",
    "message": "Provider client is not ready"
  }
}

unsupported_by_provider · 30003 · 501

渠道不支持此操作，请选择能力表中支持的操作。

处理与重试: 选择文档列为支持的渠道与动作。重复请求不会增加能力或开通内测权限。

示例 · 501 · 30003

{
  "request_id": "req_xxx",
  "error": {
    "code": "unsupported_by_provider",
    "numeric_code": "30003",
    "message": "Operation not supported by this provider"
  }
}

provider_unavailable · 30002 · 502

渠道服务暂不可用，请检查状态或稍后再试；重试写操作前先确认上次结果。

处理与重试: 再次发送前先确认原消息或回复是否已创建。超时或失败响应可能留下未知结果；后续查询未找到回复也不证明从未写入。不要自动重发。

示例 · 502 · 30002

{
  "request_id": "req_example_provider_unavailable",
  "error": {
    "code": "provider_unavailable",
    "numeric_code": "30002",
    "message": "Provider service unavailable"
  }
}

reply_post_comment_failed · 39004 · 502

核对帖子、已确认的一级评论和错误分类。写入结果未知时保留 request_id，查明后再决定是否重发；后续查询缺少回复不足以作为重试依据。

处理与重试: 再次发送前先确认原消息或回复是否已创建。超时或失败响应可能留下未知结果；后续查询未找到回复也不证明从未写入。不要自动重发。

示意 JSON；message 随实际原因变化 · 502 · 39004

{
  "request_id": "req_example",
  "error": {
    "code": "reply_post_comment_failed",
    "numeric_code": "39004",
    "message": "Failed to confirm comment reply; result may be unknown, do not automatically retry"
  }
}