{"title":"Errors & Error Handling","slug":"errors","category":"api","summary":"HTTP status code, รูปแบบ error response, และวิธีกู้คืนจาก error ทั่วไป","audience":["human","llm"],"tags":["api","errors","troubleshooting","http"],"difficulty":"beginner","updated":"2026-06-27","word_count":364,"read_minutes":2,"llm_context":"Error format: { statusCode, error, message, docs? }\nCommon errors: 401 (auth), 404 (wrong path), 429 (rate limit), 500 (server)\n401 → check Mind Key/JWT, see /docs/getting-started/authentication\n404 → wrong path, GET /endpoints for valid list, do NOT guess paths\n429 → rate limited (?key= is 60/min), use Bearer header instead\n500 → server error, retry with backoff, check /health\ndocs field in error response links to relevant documentation.\n","lang":"th","translated":true,"requested_lang":"th","content_markdown":"\n# Errors & Error Handling\n\nSynapse ใช้ HTTP status code มาตรฐานพร้อมรูปแบบ error response ที่สม่ำเสมอ เอกสารหน้านี้อธิบายวิธีตีความและกู้คืนจาก error\n\n## รูปแบบ Error Response\n\nerror ทั้งหมดส่งกลับเป็น JSON ด้วยโครงสร้างนี้:\n\n```json\n{\n \"statusCode\": 401,\n \"error\": \"Unauthorized\",\n \"message\": \"Mind Key fehlt oder ungültig.\",\n \"docs\": \"https://synapse.schaefer.zone/docs/getting-started/authentication\"\n}\n```\n\n| Field | คำอธิบาย |\n|-------|-------------|\n| `statusCode` | HTTP status code |\n| `error` | ชื่อ HTTP status |\n| `message` | คำอธิบาย error ที่มนุษย์อ่านได้ |\n| `docs` | URL ไปยังเอกสารที่เกี่ยวข้อง (เมื่อเกี่ยวข้อง) |\n\n## HTTP Status Codes\n\n### 200 OK\n\nสำเร็จ request ถูกประมวลผลถูกต้อง\n\n### 201 Created\n\nสำเร็จ สร้าง resource ใหม่ (เช่น `POST /memory`)\n\n### 204 No Content\n\nสำเร็จ ไม่มี body ส่งกลับ (เช่น `DELETE /memory/:id`)\n\n### 400 Bad Request\n\nrequest ผิดรูปแบบ สาเหตุทั่วไป:\n\n- ขาด JSON field ที่จำเป็น\n- ไวยากรณ์ JSON ไม่ถูกต้อง\n- ค่า enum ไม่ถูกต้อง (เช่น category ผิด)\n\n```json\n{\n \"statusCode\": 400,\n \"error\": \"Bad Request\",\n \"message\": \"category must be one of: identity, preference, fact, project, skill, mistake, context, note, credentials\"\n}\n```\n\n**วิธีแก้:** ตรวจสอบ request body กับ API docs ตรวจสอบว่า field ที่จำเป็นทั้งหมดมีและมีค่าที่ถูกต้อง\n\n### 401 Unauthorized\n\nการยืนยันตัวตนล้มเหลว สาเหตุทั่วไป:\n\n- ขาด `Authorization` header\n- Mind Key หรือ JWT ไม่ถูกต้อง\n- ใช้ Mind Key ในที่ที่ต้องใช้ JWT (หรือกลับกัน)\n\n```json\n{\n \"statusCode\": 401,\n \"error\": \"Unauthorized\",\n \"message\": \"Mind Key fehlt oder ungültig.\",\n \"docs\": \"https://synapse.schaefer.zone/docs/getting-started/authentication\"\n}\n```\n\n**วิธีแก้:** ตรวจสอบ token ของคุณ ดู [Authentication](/docs/getting-started/authentication)\n\n### 403 Forbidden\n\nคุณยืนยันตัวตนแล้วแต่ไม่ได้รับอนุญาตให้ทำ action นี้ สาเหตุทั่วไป:\n\n- พยายามลบ mind ของผู้ใช้อื่น\n- พยายาม verify memory ด้วย Mind Key (ต้องใช้ JWT)\n- Mind ถูกปิดใช้งาน\n\n**วิธีแก้:** ตรวจสอบว่าคุณใช้ประเภท token ที่ถูกต้องสำหรับ endpoint นี้\n\n### 404 Not Found\n\npath หรือ resource ที่ร้องขอไม่มีอยู่\n\n> [!CRITICAL]\n> **อย่าเดา path ของ endpoint** มีเพียง path ที่แสดงใน `GET /endpoints` เท่านั้นที่มีอยู่ หากคุณได้ 404 แสดงว่าคุณใช้ path ผิด\n\n```json\n{\n \"statusCode\": 404,\n \"error\": \"Not Found\",\n \"message\": \"Route GET /memory/list not found\",\n \"docs\": \"https://synapse.schaefer.zone/docs/api/errors\"\n}\n```\n\n**วิธีแก้:** เรียก `GET /endpoints` เพื่อดูรายการ endpoint ที่ถูกต้อง เปรียบเทียบ URL ของคุณกับรายการทีละตัวอักษร\n\n### 409 Conflict\n\nrequest ขัดแย้งกับสถานะที่มีอยู่ สาเหตุทั่วไป:\n\n- พยายามลงทะเบียนด้วย email ที่มีอยู่แล้ว\n- ซ้ำ webhook URL\n\n**วิธีแก้:** ใช้ค่าอื่น หรือใช้ `PUT` เพื่ออัปเดต resource ที่มีอยู่\n\n### 429 Too Many Requests\n\nคุณกระทบ rate limit ใช้เฉพาะกับ auth ผ่าน `?key=` query parameter (60/นาที)\n\n```json\n{\n \"statusCode\": 429,\n \"error\": \"Too Many Requests\",\n \"message\": \"Rate limit exceeded. Use Authorization header for unlimited access.\"\n}\n```\n\nResponse headers:\n\n```\nX-RateLimit-Limit: 60\nX-RateLimit-Remaining: 0\nRetry-After: 42\n```\n\n**วิธีแก้:** เปลี่ยนไปใช้ `Authorization: Bearer` header (ไม่จำกัดอัตรา) หรือรอ `Retry-After` วินาที\n\n### 500 Internal Server Error\n\nserver error ไม่ควรเกิดขึ้น — หากเกิด ถือเป็น bug\n\n**วิธีแก้:**\n\n1. Retry ด้วย exponential backoff (1s, 2s, 4s, 8s)\n2. ตรวจสอบ `GET /health` เพื่อดูว่า server ยังทำงานอยู่หรือไม่\n3. หากยังเกิดขึ้นเรื่อย ๆ ให้รายงาน error\n\n### 503 Service Unavailable\n\nserver ล่มชั่วคราว (เช่น ระหว่าง deploy, database migration)\n\n**วิธีแก้:** รอแล้ว retry ตรวจสอบ `GET /health`\n\n## รูปแบบการกู้คืน\n\n### Retry ด้วย exponential backoff\n\n```python\nimport time\nimport requests\n\ndef call_with_retry(url, max_retries=3):\n for attempt in range(max_retries):\n try:\n r = requests.get(url, headers={\"Authorization\": f\"Bearer {KEY}\"})\n if r.status_code == 429:\n wait = int(r.headers.get(\"Retry-After\", 60))\n time.sleep(wait)\n continue\n if r.status_code >= 500:\n time.sleep(2 ** attempt)\n continue\n return r\n except requests.RequestException:\n time.sleep(2 ** attempt)\n raise Exception(f\"Failed after {max_retries} retries\")\n```\n\n### การจัดการ auth error\n\n```python\ndef safe_call(url, key):\n r = requests.get(url, headers={\"Authorization\": f\"Bearer {key}\"})\n if r.status_code == 401:\n # Mind Key invalid — alert user\n raise AuthError(\"Mind Key invalid or expired\")\n return r\n```\n\n## สถานการณ์ error ทั่วไป\n\n### \"Mind Key fehlt oder ungültig\"\n\n- คุณลืม `Authorization` header\n- คุณใช้ `?key=` แต่ key ผิด\n- คุณใช้ JWT ในที่ที่ต้องใช้ Mind Key\n\n### \"Route not found\"\n\n- คุณเดา path ที่ไม่มีอยู่\n- คุณใช้ verb ผิด (เช่น `GET /memory` เทียบกับ `POST /memory`)\n- ตรวจสอบ `GET /endpoints` สำหรับ path ที่ถูกต้อง\n\n### \"Rate limit exceeded\"\n\n- คุณใช้ `?key=` และเกิน 60 req/min\n- เปลี่ยนไปใช้ `Authorization: Bearer` header\n\n## ขั้นตอนถัดไป\n\n- [Authentication](/docs/getting-started/authentication)\n- [API Overview](/docs/api/overview)\n- [Rate Limits](/docs/api/rate-limits)\n","content_html":"

Errors & Error Handling

\n

Synapse ใช้ HTTP status code มาตรฐานพร้อมรูปแบบ error response ที่สม่ำเสมอ เอกสารหน้านี้อธิบายวิธีตีความและกู้คืนจาก error

\n

รูปแบบ Error Response

\n

error ทั้งหมดส่งกลับเป็น JSON ด้วยโครงสร้างนี้:

\n
{\n  "statusCode": 401,\n  "error": "Unauthorized",\n  "message": "Mind Key fehlt oder ungültig.",\n  "docs": "https://synapse.schaefer.zone/docs/getting-started/authentication"\n}
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Fieldคำอธิบาย
statusCodeHTTP status code
errorชื่อ HTTP status
messageคำอธิบาย error ที่มนุษย์อ่านได้
docsURL ไปยังเอกสารที่เกี่ยวข้อง (เมื่อเกี่ยวข้อง)
\n

HTTP Status Codes

\n

200 OK

\n

สำเร็จ request ถูกประมวลผลถูกต้อง

\n

201 Created

\n

สำเร็จ สร้าง resource ใหม่ (เช่น POST /memory)

\n

204 No Content

\n

สำเร็จ ไม่มี body ส่งกลับ (เช่น DELETE /memory/:id)

\n

400 Bad Request

\n

request ผิดรูปแบบ สาเหตุทั่วไป:

\n\n
{\n  "statusCode": 400,\n  "error": "Bad Request",\n  "message": "category must be one of: identity, preference, fact, project, skill, mistake, context, note, credentials"\n}

วิธีแก้: ตรวจสอบ request body กับ API docs ตรวจสอบว่า field ที่จำเป็นทั้งหมดมีและมีค่าที่ถูกต้อง

\n

401 Unauthorized

\n

การยืนยันตัวตนล้มเหลว สาเหตุทั่วไป:

\n\n
{\n  "statusCode": 401,\n  "error": "Unauthorized",\n  "message": "Mind Key fehlt oder ungültig.",\n  "docs": "https://synapse.schaefer.zone/docs/getting-started/authentication"\n}

วิธีแก้: ตรวจสอบ token ของคุณ ดู Authentication

\n

403 Forbidden

\n

คุณยืนยันตัวตนแล้วแต่ไม่ได้รับอนุญาตให้ทำ action นี้ สาเหตุทั่วไป:

\n\n

วิธีแก้: ตรวจสอบว่าคุณใช้ประเภท token ที่ถูกต้องสำหรับ endpoint นี้

\n

404 Not Found

\n

path หรือ resource ที่ร้องขอไม่มีอยู่

\n
**อย่าเดา path ของ endpoint** มีเพียง path ที่แสดงใน `GET /endpoints` เท่านั้นที่มีอยู่ หากคุณได้ 404 แสดงว่าคุณใช้ path ผิด
{\n  "statusCode": 404,\n  "error": "Not Found",\n  "message": "Route GET /memory/list not found",\n  "docs": "https://synapse.schaefer.zone/docs/api/errors"\n}

วิธีแก้: เรียก GET /endpoints เพื่อดูรายการ endpoint ที่ถูกต้อง เปรียบเทียบ URL ของคุณกับรายการทีละตัวอักษร

\n

409 Conflict

\n

request ขัดแย้งกับสถานะที่มีอยู่ สาเหตุทั่วไป:

\n\n

วิธีแก้: ใช้ค่าอื่น หรือใช้ PUT เพื่ออัปเดต resource ที่มีอยู่

\n

429 Too Many Requests

\n

คุณกระทบ rate limit ใช้เฉพาะกับ auth ผ่าน ?key= query parameter (60/นาที)

\n
{\n  "statusCode": 429,\n  "error": "Too Many Requests",\n  "message": "Rate limit exceeded. Use Authorization header for unlimited access."\n}

Response headers:

\n
X-RateLimit-Limit: 60\nX-RateLimit-Remaining: 0\nRetry-After: 42

วิธีแก้: เปลี่ยนไปใช้ Authorization: Bearer header (ไม่จำกัดอัตรา) หรือรอ Retry-After วินาที

\n

500 Internal Server Error

\n

server error ไม่ควรเกิดขึ้น — หากเกิด ถือเป็น bug

\n

วิธีแก้:

\n
    \n
  1. Retry ด้วย exponential backoff (1s, 2s, 4s, 8s)
    2. \n
  2. ตรวจสอบ GET /health เพื่อดูว่า server ยังทำงานอยู่หรือไม่
    3. \n
  3. หากยังเกิดขึ้นเรื่อย ๆ ให้รายงาน error
    4. \n
\n

503 Service Unavailable

\n

server ล่มชั่วคราว (เช่น ระหว่าง deploy, database migration)

\n

วิธีแก้: รอแล้ว retry ตรวจสอบ GET /health

\n

รูปแบบการกู้คืน

\n

Retry ด้วย exponential backoff

\n
import time\nimport requests\n\ndef call_with_retry(url, max_retries=3):\n    for attempt in range(max_retries):\n        try:\n            r = requests.get(url, headers={"Authorization": f"Bearer {KEY}"})\n            if r.status_code == 429:\n                wait = int(r.headers.get("Retry-After", 60))\n                time.sleep(wait)\n                continue\n            if r.status_code >= 500:\n                time.sleep(2 ** attempt)\n                continue\n            return r\n        except requests.RequestException:\n            time.sleep(2 ** attempt)\n    raise Exception(f"Failed after {max_retries} retries")

การจัดการ auth error

\n
def safe_call(url, key):\n    r = requests.get(url, headers={"Authorization": f"Bearer {key}"})\n    if r.status_code == 401:\n        # Mind Key invalid — alert user\n        raise AuthError("Mind Key invalid or expired")\n    return r

สถานการณ์ error ทั่วไป

\n

"Mind Key fehlt oder ungültig"

\n\n

"Route not found"

\n\n

"Rate limit exceeded"

\n\n

ขั้นตอนถัดไป

\n\n","urls":{"html":"/docs/api/errors","text":"/docs/api/errors?format=text","json":"/docs/api/errors?format=json","llm":"/docs/api/errors?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}