Error และข้อจำกัด

โครงสร้างของ response

Response ที่สำเร็จใช้โครงสร้างเดียวกันทั้งหมด

{
  "success": true,
  "message": "Get Campaign status successfully",
  "data": { }
}

• request แบบ GET ได้ 200 ส่วนสร้าง campaign ได้ 201
• schedule, pause, resume และ cancel ได้ 200 พร้อม data: { id, status } คือ ID ของ campaign และ status ของ campaign หลังทำ request นั้นแล้ว
• endpoint ไฟล์บันทึกเสียง /record-url ส่ง field กลับมาที่ชั้นบนสุดเลย ไม่ได้อยู่ใน data

Response เมื่อเกิด error

เช็ก HTTP status code ก่อนทุกครั้ง ถ้าไม่ใช่ 2xx แปลว่าเป็น error ทุก error จาก /api/* ใช้โครงสร้างเดียวกัน

{
  "success": false,
  "statusCode": 404,
  "code": "CAMPAIGN_NOT_FOUND",
  "message": "Campaign not found",
  "errors": ["Campaign not found"]
}

Field	คำอธิบาย
success	เป็น false เสมอ
statusCode	เลขเดียวกับ HTTP status
code	รหัสตายตัวสำหรับให้โปรแกรมอ่าน ให้ใช้ field นี้ในโค้ด ดูError code
message	ประโยคภาษาอังกฤษสั้น ๆ เอาไป log หรือแสดงให้เจ้าหน้าที่ดูได้ ข้อความอาจเปลี่ยนได้ จึงไม่ควรเขียนโค้ดเทียบข้อความนี้
errors	เป็น array ของ string เสมอ ถ้าเป็น validation error จะมีปัญหาครบทุกข้อ ถ้าเป็น error แบบอื่นจะมีแค่รายการเดียว ข้อความเดียวกับ message

มี error สองตัวที่มี field เพิ่มมาอีกหนึ่งตัว

• RECIPIENT_VALIDATION_FAILED มี errorIndexes เพิ่มมา (array ของเลขแถว) ดูที่ สร้าง campaign
• RECORDING_DELETED มี expiredAt เพิ่มมา (เวลาแบบ UTC เป็น string หรือ null) ดูที่ ดึงไฟล์เสียงของ call

แนวทางเขียนโค้ดจัดการ error

ถือว่า status ที่ไม่ใช่ 2xx คือไม่สำเร็จ แยกกรณีด้วย code และ log errors ไว้ อย่า parse message

Error code

HTTP	code	เกิดเมื่อ
400	VALIDATION_FAILED	body หรือ query ไม่ถูกต้อง เช่น มี field ที่ไม่รู้จัก ขาด field ที่ต้องส่ง type ผิด page ไม่ใช่จำนวนเต็มตั้งแต่ 1 ขึ้นไป ตั้ง schedule ผิดเงื่อนไข ส่ง voice หรือเบอร์โทรออกที่ไม่มีอยู่ หรือส่ง SIP ID แบบเดิมที่ไม่ใช่ขององค์กร
400	INVALID_ID	ID ไม่ใช่ UUID อาจเป็น ID ใน path หรือ agentId ตอนสร้าง campaign
400	RECIPIENT_VALIDATION_FAILED	ตอนสร้าง campaign มี recipient อย่างน้อยหนึ่งคนที่ข้อมูลไม่ถูกต้อง ระบบจะไม่สร้างอะไรเลย
401	API_KEY_REQUIRED	ไม่ได้ส่ง header X-API-Key มา
401	INVALID_API_KEY	key ผิด หรือเป็น key เก่าที่สร้างใหม่ไปแล้ว
403	CALLING_NOT_ALLOWED	องค์กรยังไม่ได้รับสิทธิ์โทรออก จะเจอเฉพาะตอนเริ่ม campaign ให้ติดต่อ Gowajee
404	CAMPAIGN_NOT_FOUND, AGENT_NOT_FOUND, RECIPIENT_NOT_FOUND, CALL_NOT_FOUND, RECORDING_NOT_FOUND	หาไม่เจอ ID ที่เป็นขององค์กรอื่นก็นับเป็น “หาไม่เจอ” เช่นกัน
409	CAMPAIGN_NAME_TAKEN	มี campaign อื่นในองค์กรใช้ชื่อนี้อยู่แล้ว
409	CAMPAIGN_ALREADY_STARTED	สั่งเริ่ม campaign ที่ไม่ได้เป็น DRAFT campaign หนึ่งเริ่มได้ครั้งเดียว
409	INVALID_CAMPAIGN_STATE	สั่ง pause, resume หรือ cancel ตอนที่ status ไม่อนุญาต ดูเงื่อนไขการเปลี่ยน Status
410	RECORDING_DELETED	ระบบลบไฟล์บันทึกเสียงไปแล้ว เพราะครบระยะเวลาเก็บข้อมูล (data retention) ขององค์กร หรือเพราะลบ campaign ที่ไฟล์นั้นอยู่ไปแล้ว
500	INTERNAL_ERROR	ระบบฝั่งเรามีปัญหา message จะเป็น Internal server error เสมอ ให้ลองใหม่ภายหลัง ถ้ายังเจอซ้ำ ให้แจ้งทีม support ของ Gowajee พร้อมเวลาและ path ที่เรียก

บางกรณีที่เจอน้อยมาก จะได้ code กลาง ๆ ของ status นั้นแทน คือ FORBIDDEN (403), NOT_FOUND (404) หรือ CONFLICT (409) ให้จัดการเหมือน code อื่นที่ได้ status เดียวกัน

หน้าเอกสารอ้างอิงของแต่ละ endpoint บอกไว้ว่า endpoint นั้นส่ง error อะไรกลับมาได้บ้าง

ตัวอย่าง

400

{
  "success": false,
  "statusCode": 400,
  "code": "VALIDATION_FAILED",
  "message": "Validation failed",
  "errors": [
    "property maxConcurrentCalls should not exist",
    "timeWindows.0.time.0.start must be HH:MM (24-hour, two-digit hour)"
  ]
}

ถ้ามีปัญหามากกว่าหนึ่งข้อ message จะเป็น Validation failed และ errors จะมีปัญหาแยกเป็นทีละรายการ

404

{
  "success": false,
  "statusCode": 404,
  "code": "CALL_NOT_FOUND",
  "message": "Call not found",
  "errors": ["Call not found"]
}

409

{
  "success": false,
  "statusCode": 409,
  "code": "INVALID_CAMPAIGN_STATE",
  "message": "Cannot resume a CANCELLED campaign",
  "errors": ["Cannot resume a CANCELLED campaign"]
}

500

{
  "success": false,
  "statusCode": 500,
  "code": "INTERNAL_ERROR",
  "message": "Internal server error",
  "errors": ["Internal server error"]
}

สิ่งที่เปลี่ยนไปในเดือนกันยายน 2026

ถ้าเคยเชื่อมต่อกับ API เวอร์ชันเก่า ให้เช็กเรื่องเหล่านี้

• “หาไม่เจอ” ได้ 404 เสมอแล้ว เดิมบาง endpoint ส่ง 400 หรือ 500
• ชื่อ campaign ซ้ำได้ 409 แล้ว เดิมได้ 400
• ทุก error ใช้โครงสร้างด้านบน มี code และ errors เป็น array เสมอ
• schedule, pause, resume และ cancel ได้ 200 พร้อม data เดิมได้ 201 และไม่มี data
• ไฟล์บันทึกเสียงที่ลบไปแล้วได้ 410 เดิมได้ 200 พร้อม success: false
• เริ่ม campaign ไม่รับ field ที่ไม่รู้จักแล้ว รวมถึง maxConcurrentCalls และไม่รับเวลาที่ชั่วโมงไม่ครบสองหลัก (9:00) ถ้าเปิด retry ไว้ ก็ไม่รับ retryInterval ที่ต่ำกว่า 5 นาที (300000) ด้วย ดูRetry
• page ที่ไม่ใช่จำนวนเต็มตั้งแต่ 1 ขึ้นไปได้ 400 แล้ว เดิมระบบจะใช้ page 1 แทน

ข้อจำกัด

ข้อจำกัด	ค่า
ขนาด request body	20 MB หรือประมาณ 50,000–100,000 recipient ต่อการเรียก create หนึ่งครั้ง ขึ้นกับขนาดของ agentParams ถ้า body ใหญ่กว่านี้จะได้ 413 ถ้า body ไม่ใช่ JSON ที่ถูกต้องจะได้ 400 ทั้งสองกรณีระบบปฏิเสธตั้งแต่ก่อน request ไปถึง API body ที่ได้กลับมาจึง ไม่ใช่ โครงสร้างด้านบน ให้ดูจาก status code อย่างเดียว
จำนวนรายการต่อ page (/recipients, /calls)	ตายตัวที่ 100 รายการต่อ page
Rate limit	ตอนนี้ยังไม่มี limit ต่อ key แบบตายตัว ถ้าใช้ polling ให้เช็กแต่ละ campaign ทุก 1–2 นาที และไม่ถี่กว่า 30 วินาทีต่อครั้ง
จำนวน call พร้อมกัน	Gowajee ตั้ง limit ไว้ค่าเดียวสำหรับทั้งองค์กร (default 15) ทุก campaign ที่กำลังโทรใช้ limit นี้ร่วมกัน ถ้า Gowajee เพิ่ม limit ให้ จะใช้ได้เฉพาะ campaign ที่สร้างหลังจากเปลี่ยนแล้ว