# Errors & Error Handling
SUMMARY: HTTP status code, รูปแบบ error response, และวิธีกู้คืนจาก error ทั่วไป

KEY CONTEXT:
Error format: { statusCode, error, message, docs? }
Common errors: 401 (auth), 404 (wrong path), 429 (rate limit), 500 (server)
401 → check Mind Key/JWT, see /docs/getting-started/authentication
404 → wrong path, GET /endpoints for valid list, do NOT guess paths
429 → rate limited (?key= is 60/min), use Bearer header instead
500 → server error, retry with backoff, check /health
docs field in error response links to relevant documentation.

Errors & Error Handling
Synapse ใช้ HTTP status code มาตรฐานพร้อมรูปแบบ error response ที่สม่ำเสมอ เอกสารหน้านี้อธิบายวิธีตีความและกู้คืนจาก error
รูปแบบ Error Response
error ทั้งหมดส่งกลับเป็น JSON ด้วยโครงสร้างนี้:
[CODE BLOCK]
| Field | คำอธิบาย |
|-------|-------------|
|  | HTTP status code |
|  | ชื่อ HTTP status |
|  | คำอธิบาย error ที่มนุษย์อ่านได้ |
|  | URL ไปยังเอกสารที่เกี่ยวข้อง (เมื่อเกี่ยวข้อง) |
HTTP Status Codes
200 OK
สำเร็จ request ถูกประมวลผลถูกต้อง
201 Created
สำเร็จ สร้าง resource ใหม่ (เช่น )
204 No Content
สำเร็จ ไม่มี body ส่งกลับ (เช่น )
400 Bad Request
request ผิดรูปแบบ สาเหตุทั่วไป:
- ขาด JSON field ที่จำเป็น
- ไวยากรณ์ JSON ไม่ถูกต้อง
- ค่า enum ไม่ถูกต้อง (เช่น category ผิด)
[CODE BLOCK]
วิธีแก้: ตรวจสอบ request body กับ API docs ตรวจสอบว่า field ที่จำเป็นทั้งหมดมีและมีค่าที่ถูกต้อง
401 Unauthorized
การยืนยันตัวตนล้มเหลว สาเหตุทั่วไป:
- ขาด  header
- Mind Key หรือ JWT ไม่ถูกต้อง
- ใช้ Mind Key ในที่ที่ต้องใช้ JWT (หรือกลับกัน)
[CODE BLOCK]
วิธีแก้: ตรวจสอบ token ของคุณ ดู Authentication
403 Forbidden
คุณยืนยันตัวตนแล้วแต่ไม่ได้รับอนุญาตให้ทำ action นี้ สาเหตุทั่วไป:
- พยายามลบ mind ของผู้ใช้อื่น
- พยายาม verify memory ด้วย Mind Key (ต้องใช้ JWT)
- Mind ถูกปิดใช้งาน
วิธีแก้: ตรวจสอบว่าคุณใช้ประเภท token ที่ถูกต้องสำหรับ endpoint นี้
404 Not Found
path หรือ resource ที่ร้องขอไม่มีอยู่
> [!CRITICAL]
> อย่าเดา path ของ endpoint มีเพียง path ที่แสดงใน  เท่านั้นที่มีอยู่ หากคุณได้ 404 แสดงว่าคุณใช้ path ผิด
[CODE BLOCK]
วิธีแก้: เรียก  เพื่อดูรายการ endpoint ที่ถูกต้อง เปรียบเทียบ URL ของคุณกับรายการทีละตัวอักษร
409 Conflict
request ขัดแย้งกับสถานะที่มีอยู่ สาเหตุทั่วไป:
- พยายามลงทะเบียนด้วย email ที่มีอยู่แล้ว
- ซ้ำ webhook URL
วิธีแก้: ใช้ค่าอื่น หรือใช้  เพื่ออัปเดต resource ที่มีอยู่
429 Too Many Requests
คุณกระทบ rate limit ใช้เฉพาะกับ auth ผ่าน  query parameter (60/นาที)
[CODE BLOCK]
Response headers:
[CODE BLOCK]
วิธีแก้: เปลี่ยนไปใช้  header (ไม่จำกัดอัตรา) หรือรอ  วินาที
500 Internal Server Error
server error ไม่ควรเกิดขึ้น — หากเกิด ถือเป็น bug
วิธีแก้:
1. Retry ด้วย exponential backoff (1s, 2s, 4s, 8s)
2. ตรวจสอบ  เพื่อดูว่า server ยังทำงานอยู่หรือไม่
3. หากยังเกิดขึ้นเรื่อย ๆ ให้รายงาน error
503 Service Unavailable
server ล่มชั่วคราว (เช่น ระหว่าง deploy, database migration)
วิธีแก้: รอแล้ว retry ตรวจสอบ 
รูปแบบการกู้คืน
Retry ด้วย exponential backoff
[CODE BLOCK]
การจัดการ auth error
[CODE BLOCK]
สถานการณ์ error ทั่วไป
"Mind Key fehlt oder ungültig"
- คุณลืม  header
- คุณใช้  แต่ key ผิด
- คุณใช้ JWT ในที่ที่ต้องใช้ Mind Key
"Route not found"
- คุณเดา path ที่ไม่มีอยู่
- คุณใช้ verb ผิด (เช่น  เทียบกับ )
- ตรวจสอบ  สำหรับ path ที่ถูกต้อง
"Rate limit exceeded"
- คุณใช้  และเกิน 60 req/min
- เปลี่ยนไปใช้  header
ขั้นตอนถัดไป
- Authentication
- API Overview
- Rate Limits