ข้อผิดพลาด

เมื่อคำขอ API ล้มเหลว badges.ninja จะส่งคืนการตอบกลับข้อผิดพลาดแบบ JSON พร้อมรหัสสถานะ HTTP ที่เหมาะสม

รูปแบบข้อผิดพลาด

ข้อผิดพลาดทั้งหมดมีโครงสร้างดังนี้:

{
  "error": "description of what went wrong"
}

รหัสสถานะ

รหัส	ความหมาย	เกิดขึ้นเมื่อ
400	Bad Request	พารามิเตอร์ขาดหายหรือไม่ถูกต้อง ถึงขีดจำกัดของแผนหรือโควตา ฟีเจอร์ต้องใช้แผนที่สูงกว่า หรือไม่ได้รับอนุญาต — ความล้มเหลวในการตรวจสอบทั้งหมดจะส่งคืน 400
402	Payment Required	สงวนไว้สำหรับกรณีเครดิตหมด ขณะนี้ badges API ไม่หักเครดิต จึงไม่เคยส่งคืนรหัสนี้ในทางปฏิบัติ
404	Not Found	ไม่พบทรัพยากรที่ร้องขอ
500	Internal Server Error	เกิดข้อผิดพลาดที่ไม่คาดคิดบนเซิร์ฟเวอร์

ไม่มี 403 หรือ 429: ความล้มเหลวด้านการอนุญาตจะส่งคืน 400 ("not authorized") และไม่มีการจำกัดอัตราการเรียกในระดับแอปพลิเคชัน

ข้อผิดพลาดที่พบบ่อยและวิธีแก้ไข

พารามิเตอร์ที่จำเป็นขาดหาย

{ "error": "missing required parameters: name, url, email" }

วิธีแก้ไข: ใส่พารามิเตอร์ที่จำเป็นทั้งหมดในเนื้อหาคำขอ ตรวจสอบรายการทั้งหมดได้ในเอกสารของ endpoint นั้น

อีเมลไม่ถูกต้อง

{ "error": "invalid email" }

วิธีแก้ไข: ระบุที่อยู่อีเมลที่ถูกต้องในรูปแบบ user@domain.com

URL ไม่ถูกต้อง

{ "error": "invalid URL" }

วิธีแก้ไข: ระบุ URL แบบเต็มรวมถึงโปรโตคอล เช่น https://example.com.

ชื่อสั้นเกินไป

{ "error": "name must be at least 3 characters" }

วิธีแก้ไข: ใช้ชื่อที่ยาวขึ้น ชื่อผู้ออกต้องมีอย่างน้อย 3 ตัวอักษร ชื่อผู้รับต้องมีอย่างน้อย 5 ตัวอักษร

ผู้ออกยังไม่ได้รับการตรวจสอบ

{ "error": "issuer must be verified before creating badges" }

วิธีแก้ไข: ตรวจสอบผู้ออกก่อน ดูลิงก์ตรวจสอบในอีเมลของผู้ออก หรือใช้ endpoint ตรวจสอบผู้ออก

ถึงโควตาข้อมูลรับรองแล้ว (400)

{ "error": "Your Free plan reached its credential limit (1200/1200) — your allowance renews on your plan anniversary, or upgrade to Starter" }

วิธีแก้ไข: คุณใช้ข้อมูลรับรองครบตามโควตารายปีแล้ว (Free: 1,200/ปี, Starter: 12,000/ปี, Pro: 120,000/ปี) โควตาจะรีเซ็ตในวันครบรอบการลงทะเบียนบัญชีของคุณ ไม่ใช่ตามเดือนปฏิทิน อัปเกรดแผนเพื่อรับโควตาที่สูงขึ้น ดู แผนและการเรียกเก็บเงิน

ถึงขีดจำกัดของแผนแล้ว (400)

{ "error": "Your Free plan reached its issuer limit (2/2) — delete an issuer or upgrade to Starter" }

ขีดจำกัดจำนวนตราสัญลักษณ์ดิจิทัลมีรูปแบบเดียวกัน:

{ "error": "badge limit reached (5/5 on the starter plan) — delete a badge or upgrade your plan" }

วิธีแก้ไข: คุณถึงขีดจำกัดจำนวนผู้ออกหรือตราสัญลักษณ์ดิจิทัลของแผนแล้ว ลบทรัพยากรที่ไม่ได้ใช้ หรืออัปเกรดแผนของคุณ

ทรัพยากรมีความเกี่ยวข้องอยู่ (400)

{ "error": "issuer has 3 badge(s) linked — delete the badges first" }

วิธีแก้ไข: ลบตราสัญลักษณ์ดิจิทัลทั้งหมดที่เชื่อมกับผู้ออกก่อนจึงจะลบผู้ออกได้ เช่นเดียวกัน ให้ลบข้อมูลรับรองทั้งหมดภายใต้ตราสัญลักษณ์ดิจิทัลก่อนลบตราสัญลักษณ์ดิจิทัลนั้น

ไม่ได้รับอนุญาต (400)

{ "error": "not authorized" }

ความล้มเหลวด้านการอนุญาตถือเป็นข้อผิดพลาดในการตรวจสอบ จึงส่งคืน 400 (ไม่ใช่ 401 หรือ 403)

วิธีแก้ไข: คุณแก้ไขได้เฉพาะทรัพยากรที่คุณเป็นเจ้าของ ตรวจสอบให้แน่ใจว่าใช้ API key ที่ถูกต้อง

มี HTML ในข้อความแชร์

{ "error": "HTML tags are not allowed" }

วิธีแก้ไข: ข้อความแชร์ต้องเป็นข้อความธรรมดา ลบแท็ก HTML ออกจากพารามิเตอร์ text