รูปแบบข้อผิดพลาด (Error Responses)

ทุกๆ ระบบในโลกใบนี้ย่อมมีการผิดพลาด แต่ RawPush ออกแบบรูปแบบการแจ้ง Error จากฝั่ง REST API ให้มีหน้าตาเป็นมาตรฐานเดียวกันเสมอ เพื่อง่ายต่อการเอาไปผูกเงื่อนไข (Try/Catch) ลงในโค้ด Backend ของคุณ

---

📌 โครงสร้าง Error มาตรฐาน

เมื่อคำขอ REST ของคุณส่งไปแล้วไม่สำเร็จ คุณจะไม่เจอกับหน้าจอ 404 HTML ตัวอักษรกระตุกๆ แต่เราจะตอบคุณกลับเป็น JSON แบบสุภาพบุรุษเสมอ

โครงสร้าง 3 ก้อนหลักที่คุณจะได้เจอ:

{
  "success": false,
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key provided",
    "details": "Check if your secret key starts with sk_"
  }
}

• error.code: กลุ่มคีย์เวิร์ดสั้นๆ ตัวพิมพ์เล็กบอกโรค (เช่น unauthorized, bad_request, internal_error)
• error.message: คำอธิบายอักษรมนุษย์ (เพื่อเก็บลง Log file ไว้อ่านให้ทีมซัปพอร์ต)
• error.details: (อาจจะมีเพิ่มเติม) เบาะแสเพิ่มเติมเพื่อบอกให้ Backend ของคุณเดาออกว่าตายที่จุดไหนชัวร์ๆ (เช่น Payload พิมพ์ผิด)

---

🚫 1. HTTP 400 (Bad Request)

พิมพ์คำขอผิด พิมพ์ JSON ตกหล่น ส่งขนาดใหญ่เกินเหตุ

• validation_failed: ส่ง data เป็น string เปล่าๆ หรือพิมพ์ชื่อ channel ผิดกฎ ไวยากรณ์เสีย
• payload_too_large: ห่อของหนักเกินลิมิต 10KB (ห้ามส่งคลิปวิดีโอหรือรูป Base64 เต็มก้อนเข้า Publish ให้ส่งแค่ URL Link เพื่อไปโหลดต่อที่อื่น!)

---

🔒 2. HTTP 401 & 403 (Authentication & Authorization)

ระบบปฏิเสธ Key ที่คุณส่งมา

• unauthorized: ไม่แนบ Header X-Api-Key มาให้ หรือพิมพ์สลับเอา Public key มาใช้งาน
• invalid_key: Key ไม่ถูกต้อง อาจถูก Revoke ไปแล้ว หรือพิมพ์ผิด

---

🛑 3. HTTP 429 (Too Many Requests)

ระบบถูกยิงถล่มจนเกินแพกเกจปัจจุบันของโปรเจกต์นี้

• rate_limit_exceeded: ทะลุลิมิตการ Publish ต่อ 1 วินาที ที่คุณหรือโปรเจกต์ของคุณควบไว้ (แนะนำให้ไปหน้า Dashboard -> Settings ของเราเพื่อปรับตัวเลขนี้)

แนวทางแก้: ให้ Backend ของคุณทิ้งช่วงเวลารอ (Wait) แล้วค่อยยิงลองใหม่ (Retry)

---

💥 4. HTTP 5xx (Server Errors)

ความผิดไม่ได้อยู่ที่โค้ดคุณ แต่อยู่ที่ระบบฝั่งเรา

• internal_error: หากเซิร์ฟเวอร์ของเรามีปัญหา (เช่น ฐานข้อมูลชั่วคราวสะดุด) ระบบจะยอมรับผิดและแจ้ง 500 กลับไป

แนวทางแก้: ถ้าเจอรูปแบบนี้ ให้ Backend ของคุณจับเข้าคิวรอส่งใหม่ทีหลัง อย่าพึ่งตกใจทิ้งข้อมูลนั้นไป!