Preview: API ยังอยู่ระหว่างเปิดใช้ รายละเอียดอาจเปลี่ยนก่อนเปิดจริง ดูความคืบหน้าที่ บันทึกการเปลี่ยนแปลง

ข้อผิดพลาด

เมื่อคำขอไม่สำเร็จ API ตอบด้วย HTTP status ที่ตรงกับปัญหา และ body รูปแบบเดียวกันทุกครั้ง

{
  "message": "The request was refused as invalid",
  "code": "INVALID",
  "details": { "fields": ["messages.0.text"] }
}

ฟิลด์	คำอธิบาย
`message`	คำอธิบายภาษาอังกฤษสำหรับนักพัฒนา ข้อความอาจเปลี่ยนได้ จึงห้ามเขียนโค้ดตัดสินใจจากค่านี้
`code`	ค่าคงที่ที่ไม่เปลี่ยน ใช้ค่านี้ตัดสินใจในโค้ด
`details`	มีเฉพาะบาง code เช่น `fields`, `retry_after`, `reason`, `until`

ทุกคำตอบมีหัว X-Request-Id เมื่อแจ้งปัญหากับทีมงาน ให้แนบค่านี้มาด้วย คำตอบจะไม่มี stack trace หรือข้อความจากระบบภายใน

รายการ code

HTTP	`code`	ความหมาย
400	`INVALID_JSON`	body ไม่ใช่ JSON object เดียว
400	`BAD_REQUEST`	คำขอผิดรูปแบบ
401	`INVALID_TOKEN`	ไม่มี token หรือ token ใช้ไม่ได้
403	`BOT_DISABLED`	บอทถูกปิด
404	`NOT_FOUND`	ไม่มี path หรือ resource นี้
404	`UNKNOWN_VERSION`	เวอร์ชันใน path ไม่มี (ใช้ `/v1`)
405	`METHOD_NOT_ALLOWED`	path นี้ไม่รับ method นี้
408	`REQUEST_TIMEOUT`	ส่งคำขอช้าเกินไป
413	`BODY_TOO_LARGE`	body เกิน 64 KB
415	`UNSUPPORTED_MEDIA_TYPE`	ไม่ได้ส่ง `Content-Type: application/json`
422	`UNKNOWN_FIELD`	body มีฟิลด์ที่ endpoint ไม่รับ
422	`INVALID`	ค่าไม่ผ่านการตรวจ `details.fields` บอกฟิลด์ หรือ `details.reason` บอกสาเหตุ
429	`RATE_LIMITED`	เรียกเร็วเกินไป ดู `Retry-After`
431	`HEADERS_TOO_LARGE`	หัว HTTP ใหญ่เกินไป

HTTP	`code`	ความหมาย
400	`REPLY_TOKEN_INVALID`	reply token ไม่รู้จัก ใช้แล้ว หมดอายุ เป็นของบอทอื่น หรือเป็นของห้องอื่น
403	`FORBIDDEN`	บอททำสิ่งนี้ไม่ได้ `details.reason` บอกสาเหตุ: `paused`, `banned` (สถานะของบอทในห้องนี้), `attacher_lost_rights`, `plan_limit`, `owner_inactive`
403	`BANNED`	บอทอยู่ในรายชื่อแบนของห้องนี้
403	`CHAT_INACTIVE`	ห้องไม่ได้เปิดใช้งาน
403	`RESTRICTED`	บอทหรือเจ้าของถูกจำกัดสิทธิ์ (`details.until` ถ้ามี)
403	`QUOTA_EXCEEDED`	โควตารายเดือนหมด
403	`EDIT_WINDOW_PASSED`	แก้ข้อความหลัง 48 ชั่วโมงไม่ได้
422	`NOT_EDITABLE`	ข้อความนี้แก้ไม่ได้
422	`BANNED_TERM`	ข้อความมีคำต้องห้าม
422	`UNSUPPORTED_MESSAGE_TYPE`	ชนิดข้อความที่ยังไม่เปิดใช้
422	`INVALID_WEBHOOK_URL`	webhook URL ใช้ไม่ได้ (`details.reason`)
429	`SLOW_MODE`	ห้องเปิด slow mode
4xx	`REFUSED`	ถูกปฏิเสธด้วยเหตุผลอื่น

429 รอตามเวลาใน Retry-After แล้วค่อยลองใหม่
5xx ลองใหม่โดยรอนานขึ้นทีละเท่า (exponential backoff เช่น 1, 2, 4, 8 วินาที) และสุ่มเวลาเพิ่มเล็กน้อย (jitter) ตอนส่งข้อความให้ใส่ client_id ด้วย ถ้าคำขอแรกสำเร็จไปแล้ว ข้อความจะไม่ถูกโพสต์ซ้ำ
4xx อื่น ๆ อย่าส่งคำขอเดิมซ้ำ ให้แก้คำขอก่อน
v1 อาจมี code ใหม่เพิ่มขึ้น โดยไม่ถือว่าเป็นการเปลี่ยนที่ทำให้โค้ดเดิมพัง (breaking change) ถ้าโค้ดเจอ code ที่ไม่รู้จัก ให้ตัดสินจาก HTTP status แทน