การจัดการข้อผิดพลาด

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): แก้ไขโค้ดฝั่งไคลเอนต์หรือเพย์โหลด แล้วส่งคำขอใหม่ด้วย idempotency_key ชุดใหม่

🔗 เอกสารที่เกี่ยวข้อง