錯誤處理

列出 Boring API 的所有錯誤代碼、訊息與排錯建議。

回應格式

所有錯誤都會以 JSON 回傳：

{
  "success": false,
  "error": "ErrorCode",
  "message": "Human-readable error description"
}

常見 HTTP 狀態碼：

• 400：客戶端錯誤（參數或格式有誤）
• 401：驗證失敗
• 404：資源不存在
• 500：伺服端錯誤

驗證相關錯誤

InvalidApiKey

• HTTP：401
• 訊息："Invalid or missing API key"
• 原因：金鑰錯誤、缺漏、已刪除或屬於不同帳號
• 處理：
  • 確認標頭名稱為 boring-api-key
  • 金鑰需以 boring_ 開頭
  • 檢查是否有多餘空白
  • 重新產生金鑰

Unauthorized

• HTTP：401
• 訊息："Authentication required"
• 原因：控制台 Session 遺失或過期
• 處理：重新登入控制台，確保瀏覽器允許 Cookie

帳號相關錯誤

InvalidAccountId

• HTTP：400
• 訊息："Account not found or does not belong to this user"
• 原因：帳號 ID 輸入錯、已解除連結或屬於他人
• 處理：至控制台重新複製 ID，確認使用正確 Google 帳號

AccountDisabled

• HTTP：400
• 訊息："This account has been disconnected"
• 原因：帳號已在控制台解除連結
• 處理：重新連結帳號或改用其他帳號 ID

TokenExpired

• HTTP：401
• 訊息："Access token has expired"
• 原因：Instagram/Threads 權杖到期、權限被撤銷
• 處理：在控制台解除並重新連結帳號

InvalidToken

• HTTP：401
• 訊息："Token expired or revoked"
• 原因：權杖無效、權限不足、平台拒絕
• 處理：確認平台權限仍存在、重新授權或重新連結

請求格式錯誤

InvalidRequest

• HTTP：400
• 訊息："Invalid request payload"
• 原因：JSON 無效或結構錯誤
• 處理：使用 JSON 驗證工具檢查格式

MissingParameter

• HTTP：400
• 訊息："Missing required field: field_name"
• 原因：缺少必要欄位（如 post.accountId）
• 處理：補上欄位後重送

InvalidPlatform

• HTTP：400
• 訊息："Unsupported platform: value"
• 原因：platform 或 targetType 值不在支援清單
• 處理：使用 facebook、instagram、threads、x 或 youtube

InvalidTextFormat

• HTTP：400
• 訊息："Invalid text format"
• 原因：Threads 串文 text 非字串陣列、文字為空白
• 處理：使用非空字串或陣列格式

媒體相關錯誤

MediaDownloadFailed

• HTTP：400
• 訊息："Failed to download media"
• 原因：媒體 URL 無法存取、回傳非 200、需驗證
• 處理：
  • 使用 curl -I URL 測試
  • 確保使用 HTTPS
  • 媒體須可公開存取

InvalidMediaType

• HTTP：400
• 訊息："Unsupported media type"
• 原因：檔案格式不支援（例如 GIF 用於 Instagram）
• 處理：轉檔為支援格式（圖片 JPG/PNG、影片 MP4）

InvalidMediaUrl

• HTTP：400
• 訊息："Invalid media URL"
• 原因：URL 格式錯誤、非直接檔案、使用 HTTP
• 處理：提供直接指向檔案的 HTTPS URL

MediaTooLarge

• HTTP：400
• 訊息："Media exceeds maximum size"
• 原因：檔案超出平台限制（如 Twitter 影片 > 512MB）
• 處理：壓縮或轉換檔案，控制在限制內

MediaRequired

• HTTP：400
• 訊息："Media is required for this platform"
• 原因：Instagram、YouTube 等貼文未提供媒體
• 處理：加入至少一個有效媒體 URL

InvalidCarouselSize

• HTTP：400
• 訊息："Carousel must include between 2 and 10 items"
• 原因：Instagram/Facebook 輪播張數不符
• 處理：確保圖片數量在 2-10 之間（Threads 為 2-20）

文字限制

TextRequired

• HTTP：400
• 訊息："Post text is required"
• 原因：Facebook/X 需提供文字卻為空
• 處理：補上貼文文字

TextTooLong

• HTTP：400
• 訊息："Text exceeds maximum length"
• 原因：超出平台字數限制（X 為 280 字、Threads 每則 500 字）
• 處理：縮短文字或拆分串文

平台處理錯誤

PublishingFailed

• HTTP：500
• 訊息："Publishing failed: detailed message"
• 原因：平台回傳錯誤（權限、政策限制等）
• 處理：
  • 檢視 message 提示
  • 檢查平台後台是否限制
  • 如為臨時錯誤可稍後重試

VideoProcessingFailed

• HTTP：500
• 訊息："Video processing failed"
• 原因：平台無法處理影片（格式、長度）
• 處理：轉為 H.264 MP4，縮短長度，重新上傳

CarouselCreationFailed

• HTTP：500
• 訊息："Failed to create carousel"
• 原因：媒體尺寸或比例不一致
• 處理：確保所有圖片解析度、比例一致

速率與權限

RateLimitExceeded

• HTTP：429 或 400
• 訊息："Rate limit exceeded. Try again in N seconds."
• 原因：超出平台或 Boring 速率限制
• 處理：
  • 依 retry_after 等待
  • 實作指數回退
  • 分批發佈

InsufficientPermissions

• HTTP：403
• 訊息："Insufficient permissions for this action"
• 原因：權限不足（未授權留言管理、Reels 發佈等）
• 處理：重新授權並勾選所有必需權限

系統錯誤

InternalServerError

• HTTP：500
• 訊息："An unexpected error occurred"
• 處理：稍後重試，若持續發生請聯絡客服並提供錯誤訊息

ServiceUnavailable

• HTTP：503
• 訊息："Service temporarily unavailable"
• 處理：平台或 Boring 服務暫時中斷，稍待片刻再試

Timeout

• HTTP：504（或 500 + message）
• 訊息："Publishing timed out"
• 原因：影片或串文處理超時
• 處理：檢視發佈歷史是否成功，必要時重試

錯誤處理最佳實務

1. 檢查 success

result = publish_post(...)
if not result.get("success"):
    handle_error(result)

2. 實作重試

def should_retry(error_code):
    return error_code in ["RateLimitExceeded", "ServiceUnavailable", "Timeout"]

依錯誤類型決定是否重試並採用指數回退。

3. 紀錄所有錯誤

logger.error(f"API Error: {error_code} - {message}")

遇到 TokenExpired、InsufficientPermissions 等高風險錯誤時請通知維運。

4. 提供友善訊息

ERROR_MESSAGES = {
    "InvalidApiKey": "您的 API Key 無效，請到 Settings 重新產生。",
    "TokenExpired": "帳號權杖已過期，請重新連結帳號。",
    "MediaDownloadFailed": "無法下載媒體，請檢查 URL 是否可公開存取。",
    "RateLimitExceeded": "發佈過於頻繁，請稍後再試。"
}

5. 監控錯誤率

統計錯誤次數，當相同錯誤在短時間內頻繁出現時發送警示。

除錯技巧

Enable Verbose Logging

import logging
logging.basicConfig(level=logging.DEBUG)

Inspect Full Response

print(response.status_code, response.headers, response.text)

Test Media URLs

curl -I https://example.com/image.jpg

Validate JSON

json.loads(request_body)

需要更多協助？

1. 先比對本文件的錯誤說明
2. 檢查對應平台指南
3. 參考範例程式碼
4. 以最小案例重現問題
5. 確認外部平台是否故障
6. 若仍無解，請附上錯誤代碼與細節聯絡客服

下一步

• 發佈 API：了解發佈流程
• 程式範例：查看實際錯誤處理
• 平台指南：掌握平台特定限制