รหัสข้อผิดพลาด

PayerScan API ใช้รูปแบบการตอบกลับข้อผิดพลาดที่เป็นมาตรฐาน ข้อผิดพลาดทั้งหมดใช้โครงสร้างเดียวกันเพื่อให้จัดการได้ง่ายบน backend ของร้านค้า

โครงสร้างการตอบกลับข้อผิดพลาด

{
  "status": "error",
  "message": "Invalid API key. Please check your API key and try again.",
  "error_code": "INVALID_API_KEY",
  "request_id": "ORDER_123456",
  "details": { ... }
}

คุณสมบัติ:

• status: เป็น "error" เสมอ
• message: คำอธิบายข้อผิดพลาดที่อ่านได้
• error_code: รหัสข้อผิดพลาดในรูปแบบ UPPER_SNAKE_CASE ใช้ switch/case สำหรับการจัดการอัตโนมัติ
• request_id (ไม่บังคับ): รหัสคำสั่งซื้อของคุณ จะส่งกลับเฉพาะเมื่อระบุไว้ตอนสร้างใบแจ้งหนี้
• details (ไม่บังคับ): ข้อมูลเพิ่มเติมเกี่ยวกับข้อผิดพลาด (เช่น ข้อผิดพลาด validation ชื่อฟิลด์)

ตารางรหัสข้อผิดพลาด

ข้อผิดพลาดการยืนยันตัวตน

รหัสข้อผิดพลาด	HTTP	Message	วิธีแก้ไข
MISSING_API_KEY	401	Missing API key. Please provide x-api-key header.	เพิ่ม header x-api-key ในคำขอ
INVALID_API_KEY	401	Invalid API key. Please check your API key and try again.	ตรวจสอบ API key บน Dashboard
ACCOUNT_INACTIVE	403	Merchant account is inactive. Please contact support to reactivate.	ติดต่อฝ่ายสนับสนุน PayerScan
STORE_INACTIVE	403	Store is inactive. Please contact support to reactivate your store.	เปิดใช้งานร้านค้าอีกครั้งบน Dashboard
AUTHENTICATION_FAILED	500	Authentication failed. Please try again later.	ลองใหม่ภายหลัง หากยังพบปัญหา ติดต่อฝ่ายสนับสนุน

ข้อผิดพลาด validation

รหัสข้อผิดพลาด	HTTP	Message	วิธีแก้ไข
VALIDATION_ERROR	400	Validation failed. Please check your request body.	ตรวจสอบ details.errors สำหรับปัญหาเฉพาะฟิลด์
INVALID_MERCHANT_ID	400	Invalid merchant_id. The merchant_id does not match your API key.	ตรวจสอบว่า merchant_id ตรงกับร้านค้าของ API key

ข้อผิดพลาดทางธุรกิจ

รหัสข้อผิดพลาด	HTTP	Message	วิธีแก้ไข
INSUFFICIENT_BALANCE	402	Insufficient balance. Please top-up your account to continue.	เติมเงินบน PayerScan Dashboard ดู details สำหรับจำนวนเงินที่ขาด
NO_PAYMENT_METHOD	400	No payment method configured. Please add at least one wallet or exchange platform.	เพิ่มกระเป๋าเงินหรือเชื่อมต่อแพลตฟอร์มแลกเปลี่ยนบน Dashboard

ข้อผิดพลาดใบแจ้งหนี้

รหัสข้อผิดพลาด	HTTP	Message	วิธีแก้ไข
INVOICE_NOT_FOUND	404	Invoice not found.	ตรวจสอบ trans_id และยืนยันว่าเป็นของร้านค้าคุณ
MISSING_TRANS_ID	400	Missing trans_id in URL.	ใส่ trans_id ใน URL path: GET /invoice/:trans_id
INVALID_TRANS_ID_FORMAT	400	Invalid trans_id format.	ใช้รูปแบบที่ถูกต้อง: TID-XXXXXXXXXXXXXXXX

ข้อผิดพลาดขีดจำกัดอัตราการเรียก

รหัสข้อผิดพลาด	HTTP	Message	วิธีแก้ไข
RATE_LIMIT_EXCEEDED	429	Too many requests per second. / Rate limit exceeded.	รอ retry_after_seconds แล้วลองใหม่ ดู ขีดจำกัดอัตราการเรียก

ข้อผิดพลาดเซิร์ฟเวอร์

รหัสข้อผิดพลาด	HTTP	Message	วิธีแก้ไข
INTERNAL_ERROR	500	Internal server error. Please try again later.	ลองใหม่ด้วย exponential backoff หากยังพบปัญหา ติดต่อฝ่ายสนับสนุน