Claude API ตอบ Error ต้องตรวจอะไรเป็นอันดับแรก

เมื่อ Claude API ตอบ Error อย่าเพิ่งสุ่มแก้โค้ดหรือส่ง Request ซ้ำหลายครั้ง ให้เริ่มจากบันทึก HTTP status, ข้อความ Error และ Request ID ก่อน แล้วตรวจ API key, สิทธิ์บัญชี, รูปแบบ Request และขีดจำกัดการใช้งานตามลำดับ

วิธีนี้ช่วยแยกได้ว่าปัญหาเกิดจาก Request ของแอป การตั้งค่าบัญชี หรือระบบ API ชั่วคราว

❶ เก็บรายละเอียด Error ก่อนแก้

ตรวจข้อมูลเหล่านี้จาก Response หรือ Log:

• HTTP status เช่น 400, 401, 403, 429 หรือ 500
• ค่า error.type และ error.message
• request_id ใน Response body หรือ request-id ใน Header
• Endpoint, ชื่อโมเดล และเวลาที่เกิดปัญหา
• หากใช้ SDK ให้บันทึกชนิด Exception ที่ SDK ส่งกลับ

อย่าบันทึก API key, Authorization header หรือข้อมูลลับของผู้ใช้ลง Log ที่แชร์ให้ผู้อื่น หากต้องส่งข้อมูลให้ฝ่ายช่วยเหลือ ให้เก็บ Request ID และตัดข้อมูลรับรองออกก่อน

❷ ใช้ HTTP status ระบุจุดตรวจเบื้องต้น

Status	ความหมายทั่วไป	สิ่งที่ควรตรวจ
400	รูปแบบหรือเนื้อหา Request มีปัญหา	พารามิเตอร์ ข้อความ และรูปแบบข้อมูล
401	ปัญหาการยืนยันตัวตน	API key ถูกต้อง ยังไม่หมดอายุหรือถูกยกเลิก
402	ปัญหาการชำระเงิน	ข้อมูล Billing และสถานะการชำระเงิน
403	ไม่มีสิทธิ์ใช้ทรัพยากร	สิทธิ์ Organization, Workspace และโมเดล
404	ไม่พบ Endpoint หรือ Resource	URL, Endpoint และ Resource ID
409	Request ขัดกับสถานะปัจจุบัน	การแก้ไขข้อมูลพร้อมกันหรือค่าที่ต้องไม่ซ้ำ
413	Request ใหญ่เกินขนาดที่รองรับ	ขนาดข้อความ ไฟล์ ภาพ และจำนวนข้อมูล
429	Rate limit หรือขีดจำกัดการใช้จ่าย	Rate limit, Spend cap และ Header retry-after
500	ข้อผิดพลาดภายในระบบ	ลองใหม่แบบเว้นช่วง หากเกิดซ้ำให้แจ้ง Support พร้อม Request ID
504	Request ใช้เวลานานจนหมดเวลา	ใช้ Streaming หรือแบ่งงานให้สั้นลง
529	API รองรับคำขอไม่ไหวชั่วคราว	รอแล้วลองใหม่โดยเว้นช่วง

Status เป็นจุดเริ่มวิเคราะห์ ไม่ใช่คำตอบทั้งหมด ให้อ่าน error.type และ error.message ประกอบด้วย

❸ ตรวจ API key และสิทธิ์บัญชี

หากได้ 401 authentication_error ให้ตรวจว่าใช้ API key จาก Console ถูกตัว ไม่ได้พิมพ์ผิด ถูกยกเลิก หรือหมดอายุ และส่งผ่าน Header ตามวิธีของ SDK หรือ API ที่ใช้

หากได้ 403 permission_error ให้ตรวจว่า Workspace หรือ Organization มีสิทธิ์เรียกโมเดลหรือ Endpoint นั้นหรือไม่ บัญชี AWS หรือ Google Cloud ที่ใช้เรียกผ่านผู้ให้บริการคลาวด์ก็ต้องมี Credentials และสิทธิ์ตามระบบนั้นด้วย

❹ ตรวจ Endpoint และรูปแบบ Request

หากได้ 400 หรือ 404 ให้ตรวจ:

1. URL และ Endpoint สะกดถูกหรือไม่
2. ชื่อโมเดลและ Resource ID ถูกต้องหรือยังใช้งานได้หรือไม่
3. มีพารามิเตอร์ที่ไม่รองรับสำหรับโมเดลนั้นหรือไม่
4. รูปแบบ messages, tools และ max_tokens ถูกต้องหรือไม่
5. หากนำผลลัพธ์จากรอบก่อนกลับไปส่ง ต้องคงโครงสร้างข้อมูลที่ API กำหนด

หากเพิ่งเปลี่ยนโมเดล ให้ตรวจเอกสารของโมเดลนั้นโดยเฉพาะ เพราะพารามิเตอร์บางอย่างอาจรองรับไม่เหมือนกัน

❺ ตรวจ Request ใหญ่เกินไปหรือไม่

ถ้าเจอ 413 request_too_large ให้ตรวจขนาด Request ตาม Endpoint ที่ใช้ เอกสาร API ระบุขนาดสูงสุดของ Messages และ Token Counting ที่ 128 MB, Batch ที่ 256 MB และ Files API ที่ 500 MB

หากข้อมูลเกินขนาด ให้ลดจำนวนไฟล์หรือภาพ แบ่งเนื้อหาเป็นหลาย Request หรือใช้ Endpoint ที่เหมาะกับงาน แต่อย่าลดข้อมูลสำคัญโดยไม่ตรวจว่าผลลัพธ์ยังตอบโจทย์อยู่

❻ รับมือ 429, 500, 504 และ 529

สำหรับ 429 ให้ตรวจ Rate limit และ Spend cap หากมี Header retry-after ให้รอตามเวลาที่ระบุ แต่ถ้าเป็นการถึง Spend cap บางกรณีอาจไม่มี Header นี้ และ Request จะยังไม่สำเร็จจนกว่าจะมีการคืนสิทธิ์ใช้งานหรือปรับขีดจำกัด

สำหรับ 500 หรือ 529 ให้ลองใหม่ด้วยการเว้นช่วงเพิ่มขึ้นทีละขั้น แทนการส่งซ้ำถี่ ๆ SDK ทางการรองรับการลองใหม่สำหรับความผิดพลาดชั่วคราวหลายชนิดอยู่แล้ว

ถ้าเป็น Request ระยะยาวและได้ 504 ให้พิจารณาใช้ Messages API แบบ Streaming หรือแบ่งงานเป็นส่วนที่สั้นลง

❼ ตรวจ Error ที่เกิดระหว่าง Streaming

การใช้ Streaming อาจเริ่มต้นด้วย HTTP 200 แต่เกิด Error ระหว่างส่ง Event ภายหลังได้ จึงควรตรวจ Event ของ Stream ให้ครบ ไม่ดูเฉพาะ Status ตอนเริ่มเชื่อมต่อ

หากแอปตัดการเชื่อมต่อก่อนรับ Event สุดท้าย ให้ตรวจ Log ของ Client, Proxy และเครือข่าย รวมถึงดูว่ามีการจัดการ Event ประเภท Error ใน Stream แล้วหรือไม่

ComSiam แนะนำให้เก็บ Request ID ที่สัมพันธ์กับ Error ทุกครั้ง และใช้ ID นั้นเมื่อติดต่อฝ่ายช่วยเหลือ แทนการส่ง API key หรือข้อมูลรับรองไปด้วย

❽ คำถามที่พบบ่อย

ควรเริ่มตรวจตรงไหนเมื่อ API ตอบ Error?

เริ่มจาก HTTP status, error.type, error.message และ Request ID จากนั้นตรวจ API key สิทธิ์ Request และขีดจำกัดตามชนิด Error

Error 429 หมายถึงส่ง Request ถี่เกินไปเสมอหรือไม่?

ไม่เสมอไป อาจเกิดจาก Rate limit, Spend cap หรือข้อจำกัดการใช้จ่ายของ Workspace ให้ตรวจ Header retry-after และข้อมูล Spend limit ด้วย

ทำไมได้ 200 แต่ยังมี Error ในผลลัพธ์?

หากใช้ Streaming Error อาจเกิดหลังเริ่ม Response แล้ว ให้ตรวจ Event ภายใน Stream ไม่ใช่ดูแค่ HTTP status แรก

ส่งอะไรให้ Support เพื่อช่วยตรวจปัญหา?

แจ้ง Request ID, เวลาเกิดปัญหา, Endpoint, HTTP status และข้อความ Error โดยตัด API key, Authorization header และข้อมูลลับออกก่อน

❾ สรุป

เมื่อ Claude API ตอบ Error ให้เก็บรายละเอียด Response ก่อน แล้วใช้ Status code ช่วยชี้จุดตรวจ ตรวจ Credentials และสิทธิ์เมื่อเป็น 401 หรือ 403 ตรวจ Request เมื่อเป็น 400, 404 หรือ 413 และจัดการ 429, 500, 504 หรือ 529 ตาม Rate limit และลักษณะการทำงาน

ComSiam แนะนำให้ปรับระบบ Log ให้เก็บ Request ID และชนิด Error โดยไม่บันทึก API key วิธีนี้ช่วยให้ทั้งทีมแก้ปัญหาได้เร็วขึ้นและแจ้ง Support ได้ตรงจุด