エラーハンドリング

ANKK パブリック API は、詳細なエラー JSON ボディを伴う標準的な HTTP ステータスコードを返します。

📌 標準エラー形式

すべてのエラーレスポンスは以下の形式に従います。

{
  "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 Insufficient Scope (スコープ不足)

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

2. 409 Idempotency Conflict (べき等性の競合)

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

3. 400 Media Validation Failed (メディア検証失敗)

{
  "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): クライアントコードまたはペイロードを修正し、新しいべき等キーで再発行してください。

🔗 関連ドキュメント