錯誤

每個錯誤都會回傳 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 用來識別請求：聯絡支援團隊時請提供它。

OAuth 端點（/v1/oauth/token、/v1/oauth/authorize）依 RFC 6749 的格式回應：{ "error": "invalid_grant", "error_description": "…" }。

錯誤碼

狀態碼	錯誤碼	意義
400	`invalid_request`	請求本文、查詢或某個參數無效。每個被拒絕的欄位對應一則詳細資料：`field`、`code`（`required`、`is_string`、`max`……）和 `message`。
400	`invalid_json`	請求本文不是有效的 JSON。
400	`invalid_cursor`	該游標不是由 Sofia API 回傳的。
400	`webhook_url_invalid`	webhook 位址不是 https，或指向私人位址。
400	`webhook_event_invalid`	未知的 webhook 事件。
400	`application_name_invalid`	設定 › API:用戶端名稱缺失或過長。
400	`application_profile_invalid`	設定 › API:用戶端資料中有欄位無效;詳細資料會指出是哪一個。
400	`logo_invalid`	設定 › API:標誌被拒絕(至少 180×180 px,PNG、JPEG 或 WebP,最大 2 MB)。
401	`invalid_token`	權杖缺失、未知、已過期或已被撤銷，或權杖背後的使用者已失去其所帶的權限。請參閱 `WWW-Authenticate` 標頭。
401	`unauthorized`	需要驗證。
402	`subscription_required`	live 寫入（包括試跑）需要有效的訂閱或試用。
403	`insufficient_scope`	權杖缺少該端點所需的 scope；詳細資料中會指出是哪一個。
403	`insufficient_role`	你在此 Workspace 中的角色不允許執行該動作。
403	`live_mode_required`	用測試權杖進行了真實寫入。
403	`route_closed_to_applications`	該端點不對應用程式開放。
403	`forbidden`	存取被拒絕。
403	`session_required`	設定 › API:此操作需要 Sofia 工作階段,而不是權杖。
403	`impersonation_forbidden`	設定 › API:此操作在借用的工作階段中會被拒絕。
403	`workspace_owner_required`	只有 Workspace 的擁有者可以執行此操作。
403	`workspace_member_required`	你不是此 Workspace 的成員。
404	`route_not_found`	沒有端點回應該方法和路徑。
404	`establishment_not_found`	未知的門市，或超出權杖的存取範圍。
404	`media_not_found`	未知的媒體，或超出權杖的存取範圍。
404	`post_not_found`	未知的貼文，或超出權杖的存取範圍。
404	`webhook_not_found`	未知的 webhook，或屬於另一個應用程式。
404	`not_found`	資源不存在。
404	`application_not_found`	設定 › API:未知的用戶端。
404	`grant_not_found`	授權未知,或已被撤銷。
404	`personal_key_not_found`	設定 › API:未知的個人金鑰。
404	`consent_not_found`	授權請求已過期或不存在:請從授權端點重新開始。
405	`method_not_allowed`	此端點不允許使用該方法。
409	`post_in_flight`	有網路正在傳送該貼文：請稍後重試刪除。
409	`post_not_editable`	已有網路送出了該貼文：不能再編輯。
409	`account_already_connected`	該網路已連結到此門市。
409	`webhook_limit_reached`	該應用程式已有 10 個 webhook。
409	`idempotency_in_progress`	使用此 `Idempotency-Key` 的第一個請求仍在處理中。
409	`conflict`	請求與資源的目前狀態衝突。
409	`scope_removal_forbidden`	設定 › API:用戶端的權限可以新增,但不能移除。
409	`public_client_has_no_secret`	設定 › API:公開用戶端沒有密鑰。
413	`payload_too_large`	檔案超出上傳限制。
415	`unsupported_media_type`	不支援的內容類型。
422	`post_refused`	某個網路、門市或你的方案會拒絕該貼文。每個原因對應一則詳細資料，各自帶有 `message`。
422	`media_import_refused`	無法從該 URL 匯入媒體；詳細資料中給出了原因。
422	`media_upload_refused`	上傳的檔案不是支援的圖片或影片。
422	`platform_not_offered`	該網路不提供連結。
422	`idempotency_key_reused`	此 `Idempotency-Key` 曾用於另一個請求本文。
422	`unprocessable_entity`	請求可以理解,但無法處理。
429	`rate_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_past`	`scheduledAt` 在過去。
`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。