Reason code ที่คงที่
Error code ที่คงที่ใช้ใน client logic, reports และการ route support requests แบบอัตโนมัติ
Documentation / API Errors
การจัดการ API errors
รูปแบบเดียวสำหรับ responses, error codes, temporary failures, unknown results, diagnostics และ safe recovery สำหรับ iGaming integrations
HTTP
ผลลัพธ์ของ request
Codes
เหตุผลที่ชัดเจน
Retry
การดำเนินการที่ปลอดภัย
ค้นหา
request diagnostics
วงจรการจัดการ error
จาก API response ไปสู่ recovery
01
ระบุประเภทผลลัพธ์
ตรวจสอบ HTTP status, reason code, error category และ operation state
02
บันทึกข้อมูลเพื่อวิเคราะห์
บันทึก request ID และ operation ID, endpoint, เวลา, provider reference และ parameters ที่ปลอดภัย
03
เลือกการดำเนินการที่ปลอดภัย
แก้ไขข้อมูล หยุด operation, retry request หลังเว้นช่วง หรือเช็กสถานะปัจจุบัน
04
กู้คืนและควบคุม
ป้องกันรายการซ้ำ ทำ reconciliation แจ้งผู้รับผิดชอบ และปิดสาเหตุของปัญหา
ภาพรวม
Error ต้องอธิบายสาเหตุและขั้นตอนถัดไป
HTTP 400 หรือ 500 เพียงอย่างเดียวไม่เพียงพอ API ที่เชื่อถือได้ควรส่ง reason code ที่คงที่ เชื่อม response กับ request ID และช่วยให้เข้าใจว่าต้องแก้ข้อมูล หยุด operation, retry request หรือเช็กสถานะแยกต่างหาก
การดำเนินการที่คาดเดาได้
Error category ระบุว่า retry ได้หรือไม่ และต้องแก้ข้อมูลใด
การเชื่อมโยงเพื่อ diagnostics
Request ID, operation ID และ provider ID เชื่อม client logs กับ internal systems และ support
โครงสร้าง error
โครงสร้าง error response ที่แนะนำ
Response ควรกระชับ คงที่ และเหมาะกับ automatic processing โดยไม่เปิดเผย internal implementation หรือ sensitive data
Error code
ตัวระบุสาเหตุที่คงที่ ซึ่งไม่เปลี่ยนแม้แก้ข้อความอธิบาย
คำอธิบาย
คำอธิบายสั้นและปลอดภัย โดยไม่มี internal code, database queries, secrets หรือรายละเอียดที่ไม่จำเป็น
Request ID
Unique ID สำหรับค้นหา operation ใน logs และใช้ติดต่อ support
ข้อมูลเพิ่มเติม
สถานะที่อนุญาต limit, current state หรือ safe rejection reason
Retry ได้
สัญญาณชัดเจนว่าเป็น temporary error โดยยังต้องมีการป้องกัน operation ไม่ให้ทำซ้ำ
เว้นช่วงก่อน retry
เวลาหน่วงที่แนะนำเป็นวินาที หรือ HTTP header สำหรับ rate limiting และ temporary unavailability
Field errors
รายการ fields ที่มีปัญหา พร้อม reason code, value path และคำอธิบายที่ปลอดภัย
ลิงก์เอกสาร
ลิงก์ถาวรหรือ section ID ที่อธิบายสาเหตุและวิธีแก้
ประเภทของ errors
ประเภท error หลัก
HTTP status แสดง class ของผลลัพธ์โดยรวม ส่วน internal code ระบุสาเหตุและ action ที่อนุญาตอย่างเจาะจง
Input validation error
รูปแบบไม่ถูกต้อง ขาด required field, unsupported value, amount precision ผิด หรือ request structure ไม่ถูกต้อง
Authentication error
Token หาย หมดอายุ หรือไม่ถูกต้อง, API key, signature, request time หรือ one-time identifier ผิด
สิทธิ์ไม่เพียงพอ
Client ถูกระบุได้ แต่ไม่มี role, brand, market หรือ permission ที่ต้องใช้
ไม่พบ object
Player, payment, round, KYC check, provider หรือ object อื่นไม่มีอยู่หรือ client ไม่มีสิทธิ์เข้าถึง
State conflict
เวอร์ชันหรือสถานะของ object เปลี่ยนไป หรือ operation ID ถูกใช้แล้วกับ parameters อื่น
ผิด business rule
ยอดคงเหลือไม่พอ เกิน limit, player ถูกบล็อก market ถูกห้าม หรือ status transition ไม่ถูกต้อง
Request มากเกินไป
จำนวน requests เกิน limit ที่อนุญาตสำหรับ client, method, role หรือ critical operation
Provider ไม่พร้อมใช้งาน
External service ไม่พร้อมใช้งาน ตอบช้า หรือไม่รับ operations ชั่วคราว
Internal error
เกิด platform error ที่ไม่คาดคิด โดยไม่เปิดเผยรายละเอียดภายใน แต่มี identifier สำหรับ diagnostics
Retry และ recovery
Retry request และผลลัพธ์ไม่ทราบแน่ชัด
Retry จะปลอดภัยต่อเมื่อระบุประเภท error แล้วและตรวจสอบว่า original operation อาจทำสำเร็จไปแล้วหรือไม่
01
ตรวจสอบว่า retry ได้หรือไม่
Data, permission และ business rule errors โดยทั่วไปต้องแก้ request ไม่ใช่ส่งซ้ำ
02
ใช้ operation key เดิม
การ retry financial, gaming หรือ critical operation อื่น ต้องไม่สร้างผลลัพธ์ใหม่
03
เพิ่มช่วงเวลาระหว่าง attempts
เพิ่ม interval ทีละขั้น คำนึงถึงเวลาที่ server ระบุ และจำกัดจำนวน attempts รวม
04
หยุดและส่งต่อให้ตรวจสอบ
เมื่อใช้ attempts ครบแล้ว ให้บันทึก operation ว่ายังไม่เสร็จและส่งไป manual review หรือ reconciliation
ไม่มี response ไม่ได้แปลว่า operation ล้มเหลว
หาก connection หลุดหลังส่ง request ผลลัพธ์อาจยังไม่ทราบ ก่อน retry ต้องเช็กสถานะด้วย operation ID หรือรอ trusted notification
Diagnostics และ control
Logs, identifiers, metrics และ alerts
Diagnostics ควรทำให้ติดตาม request path ระหว่าง platform, adapter และ external provider ได้ โดยไม่เก็บ sensitive data เกินจำเป็น
Context สำหรับวิเคราะห์
Request ID, correlation ID, operation ID และ external provider ID
Endpoint, HTTP method, environment, client, เวลา และ response duration
HTTP status, error code, จำนวน attempts และ final state
Masked sensitive fields, safe headers และผลการตรวจ signature
Monitoring และ alerts
Error rate ตาม method, provider, client และ reason category
การเพิ่มขึ้นของ long responses, HTTP 5xx, invalid signatures และ rate limits
จำนวน retries, operations ที่ผลลัพธ์ไม่ทราบ และ recovery tasks
Alerts พร้อม thresholds, owners และ escalation rules
Testing
สิ่งที่ต้องทดสอบใน test environment
Test environment ควรจำลอง error category สำคัญทั้งหมดและยืนยันว่า client, retries และ controls ทำงานถูกต้อง
Input data errors
Required fields ที่ขาด, data types ผิด, unsupported values, amount precision และหลาย errors พร้อมกัน
Access และ permissions
Invalid key, expired token, invalid signature, unauthorized role, blocked IP และ repeated one-time identifier
ไม่มี response และผลลัพธ์ไม่ทราบ
Connection หลุดก่อนส่ง หลังรับ operation หรือระหว่างรอ final response
Rate limiting
HTTP 429, recommended delay, parallel requests และ recovery หลัง limit สิ้นสุด
Provider errors
Unavailable, maintenance, invalid response, delayed notification และ conflicting status
Retry และ protective stop
จำกัดจำนวน attempts, เพิ่ม delay, หยุด requests ชั่วคราว, controlled recovery และ manual escalation
Checklist ก่อน launch
Production integration ควร launch หลังตรวจ error structure, client behavior, duplicate protection และ diagnostics
Errors ทั้งหมดส่ง reason code ที่คงที่และ request ID
Error details ไม่เปิดเผย secrets หรือ internal implementation
Temporary และ permanent error categories มีระบุไว้ใน documentation
Retry critical operation ใช้ duplicate-protection key เดิม
Unknown result จัดการผ่าน status check หรือ trusted notification
ตั้งค่า logs, metrics, alerts, recovery queue และ escalation rules แล้ว
ต้องการทำ API errors ให้เป็น format เดียวกันไหม
ส่ง HTTP responses ปัจจุบัน, error codes, retry rules และ problematic scenarios มาให้ APIACE จะช่วยกำหนด unified error model, safe recovery และ control