错误

获取 API 密钥

每个错误都会返回 HTTP 状态码和相同的 JSON 结构。code 是你的代码应当读取的契约；message 是写给人看的，可能会变化。

json
{
  "error": {
    "code": "invalid_request",
    "message": "The request is invalid",
    "details": [
      { "field": "targets[0].text", "code": "required", "message": "targets[0].text is required" }
    ],
    "docUrl": "https://www.sofia-post.com/developers/errors#invalid_request",
    "requestId": "2aab5943-6333-4caf-8478-25a85ebd4abf"
  }
}
  • details 提供更多信息：被拒绝的字段、某个网络的原因、已用尽的速率限制窗口。
  • docUrl 指向本页对该错误码的说明。
  • requestId 用于标识请求：联系支持时请提供它。

错误码

状态码错误码含义
400invalid_request请求体、查询或某个参数无效。每个被拒绝的字段对应一条详情：field、code（required、is_string、max……）和 message。
400invalid_json请求体不是有效的 JSON。
400invalid_cursor该游标不是由 Sofia API 返回的。
400webhook_url_invalidwebhook 地址不是 https，或指向私有地址。
400webhook_event_invalid未知的 webhook 事件。
400application_name_invalid设置 › API:客户端名称缺失或过长。
400application_profile_invalid设置 › API:客户端资料中有字段无效;详情会指出是哪一个。
400logo_invalid设置 › API:徽标被拒绝(至少 180×180 px,PNG、JPEG 或 WebP,最大 2 MB)。
401invalid_token令牌缺失、未知、已过期或已被撤销，或令牌背后的用户已失去其所带的权限。参见 WWW-Authenticate 请求头。
401unauthorized需要身份验证。
402subscription_requiredlive 写入（包括试运行）需要有效的订阅或试用。
403insufficient_scope令牌缺少该端点所需的 scope；详情中会指出是哪一个。
403insufficient_role你在此 Workspace 中的角色不允许执行该操作。
403live_mode_required用测试令牌进行了真实写入。
403route_closed_to_applications该端点不对应用开放。
403forbidden访问被拒绝。
403session_required设置 › API:此操作需要 Sofia 会话,而不是令牌。
403impersonation_forbidden设置 › API:此操作在借用的会话中会被拒绝。
403workspace_owner_required只有 Workspace 的所有者可以执行此操作。
403workspace_member_required你不是此 Workspace 的成员。
404route_not_found没有端点响应该方法和路径。
404establishment_not_found未知的门店，或超出令牌的访问范围。
404media_not_found未知的媒体，或超出令牌的访问范围。
404post_not_found未知的帖子，或超出令牌的访问范围。
404webhook_not_found未知的 webhook，或属于另一个应用。
404not_found资源不存在。
404application_not_found设置 › API:未知的客户端。
404grant_not_found授权未知,或已被撤销。
404personal_key_not_found设置 › API:未知的个人密钥。
405method_not_allowed此端点不允许使用该方法。
409post_in_flight有网络正在发送该帖子：请稍后重试删除。
409post_not_editable已有网络发送了该帖子：不能再编辑。
409account_already_connected该网络已连接到此门店。
409webhook_limit_reached该应用已有 10 个 webhook。
409idempotency_in_progress使用此 Idempotency-Key 的第一个请求仍在处理中。
409conflict请求与资源的当前状态冲突。
409scope_removal_forbidden设置 › API:客户端的权限可以添加,但不能移除。
409public_client_has_no_secret设置 › API:公开客户端没有密钥。
413payload_too_large文件超出上传限制。
415unsupported_media_type不支持的内容类型。
422post_refused某个网络、门店或你的套餐会拒绝该帖子。每个原因对应一条详情，各自带有 message。
422media_import_refused无法从该 URL 导入媒体；详情中给出了原因。
422media_upload_refused上传的文件不是受支持的图片或视频。
422platform_not_offered该网络不提供连接。
422idempotency_key_reused此 Idempotency-Key 曾用于另一个请求体。
422unprocessable_entity请求可以理解,但无法处理。
429rate_limit_exceeded速率限制窗口已满：请等待 Retry-After 指定的时间。

帖子被拒绝的原因

post_refused 会在 details[].code 中列出每个原因：

错误码含义
unsupported_platform不支持该网络。
duplicate_platform同一个网络被指定了两次。
unsupported_format该网络不提供这种格式。
caption_too_long文本过长（max、actual）。
too_many_hashtags话题标签过多（max、actual）。
too_many_mentions@ 提及过多（max、actual）。
too_many_thread_posts串文过长（max、actual）。
too_many_media媒体过多（max、actual）。
media_mix_refused该网络不允许混合照片和视频。
media_required该网络需要照片或视频。
media_type_refused该网络不接受这种类型的媒体。
scheduled_in_pastscheduledAt 在过去。
scheduled_at_invalid定时帖子需要未来的 scheduledAt。
account_not_connected此门店在该网络上没有已连接的账号。
account_ambiguous该网络上连接了多个账号：请用 accountId 指定一个。
media_not_found该媒体不在此门店的媒体库中。
media_url_invalid媒体 URL 必须是公开的 https 地址。
platform_unavailable该网络在 Sofia 上尚未开放。
publication_quota_exceeded已达到你套餐的发布配额。

处理错误

  • 根据 code 分支处理，绝不要依据 message。
  • 429 在 Retry-After 之后重试，5xx 使用指数退避重试。
  • 切勿原样重试 4xx：先修正请求。
  • 每次失败都记录 requestId。