錯誤處理

ANKK Public API 會傳回標準 HTTP 狀態碼，以及包含詳細資訊的 JSON 錯誤內容。

📌 標準錯誤架構

所有錯誤回應均遵循以下架構：

{
  "error": "idempotency_conflict",
  "message": "The idempotency key was already used with a different request payload.",
  "param": "idempotency_key"
}

🚦 HTTP 狀態碼參考

狀態碼	錯誤碼	意義與建議操作
`400 Bad Request`	`invalid_input`, `validation_failed`	格式錯誤的請求主體或參數。請修正酬載。
`401 Unauthorized`	`unauthorized`, `invalid_api_key`	缺少或無效的 API 金鑰。
`403 Forbidden`	`insufficient_scope`, `quota_exceeded`	缺少權限範圍或超出方案配額。
`404 Not Found`	`not_found`	找不到資源 (`content_id`, `connection_id`)。
`409 Conflict`	`idempotency_conflict`	冪等性金鑰被重複使用於不匹配的酬載。
`423 Locked`	`brand_locked`	品牌因帳單或政策而被鎖定。請檢查帳單。
`429 Too Many Requests`	`rate_limited`	超出速率限制。請根據 `Retry-After` 延後重試。
`500 Server Error`	`internal_server_error`	伺服器內部問題。可配合退避策略重試。
`503 Service Unavailable`	`sns_provider_unavailable`	外部社群網路服務中斷。請稍後重試。

🔍 常見業務錯誤範例

1. 403 權限範圍不足

{
  "error": "insufficient_scope",
  "message": "The API key does not have the required 'publishing:create' scope."
}

2. 409 冪等性衝突

{
  "error": "idempotency_conflict",
  "message": "Idempotency key 'launch-001' is already bound to a different request hash.",
  "param": "idempotency_key"
}

3. 400 媒體驗證失敗

{
  "error": "sns_content_media_maximum_exceeded",
  "message": "Bluesky supports a maximum of 4 images per post.",
  "param": "media"
}

🔁 安全重試策略

可重試 (5xx, 網路逾時)：使用完全相同的 idempotency_key 重新發送，並配合指數抖動退避策略。
不可重試 (400, 401, 403, 404, 409)：修改用戶端程式碼或酬載，再使用新的冪等性金鑰重新發出請求。

🔗 相關文件