{"title":"Errors & Error Handling","slug":"errors","category":"api","summary":"Kode status HTTP, format respons error, dan cara memulihkan diri dari error umum.","audience":["human","llm"],"tags":["api","errors","troubleshooting","http"],"difficulty":"beginner","updated":"2026-06-27","word_count":499,"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":"id","translated":true,"requested_lang":"id","content_markdown":"\n# Errors & Error Handling\n\nSynapse menggunakan kode status HTTP standar dengan format respons error yang\nkonsisten. Halaman ini menjelaskan cara menafsirkan dan memulihkan diri dari\nerror.\n\n## Format Respons Error\n\nSemua error mengembalikan JSON dengan struktur berikut:\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 | Deskripsi |\n|-------|-------------|\n| `statusCode` | Kode status HTTP |\n| `error` | Nama status HTTP |\n| `message` | Deskripsi error yang dapat dibaca manusia |\n| `docs` | URL ke dokumentasi terkait (jika tersedia) |\n\n## Kode Status HTTP\n\n### 200 OK\n\nBerhasil. Permintaan diproses dengan benar.\n\n### 201 Created\n\nBerhasil. Sumber daya baru dibuat (mis. `POST /memory`).\n\n### 204 No Content\n\nBerhasil. Tidak ada body yang dikembalikan (mis. `DELETE /memory/:id`).\n\n### 400 Bad Request\n\nPermintaan tidak valid. Penyebab umum:\n\n- Field JSON yang wajib tidak ada\n- Sintaks JSON tidak valid\n- Nilai enum tidak valid (mis. kategori salah)\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**Perbaikan:** Periksa body permintaan terhadap dokumentasi API. Pastikan\nsemua field yang wajib ada dan memiliki nilai yang valid.\n\n### 401 Unauthorized\n\nAutentikasi gagal. Penyebab umum:\n\n- Header `Authorization` tidak ada\n- Mind Key atau JWT tidak valid\n- Menggunakan Mind Key di mana JWT diperlukan (atau sebaliknya)\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**Perbaikan:** Verifikasi token Anda. Lihat [Autentikasi](/docs/getting-started/authentication).\n\n### 403 Forbidden\n\nAnda terautentikasi tetapi tidak diizinkan melakukan tindakan ini. Penyebab umum:\n\n- Mencoba menghapus mind pengguna lain\n- Mencoba memverifikasi memori dengan Mind Key (memerlukan JWT)\n- Mind dinonaktifkan\n\n**Perbaikan:** Periksa apakah Anda menggunakan tipe token yang benar untuk endpoint ini.\n\n### 404 Not Found\n\nPath atau sumber daya yang diminta tidak ada.\n\n> [!CRITICAL]\n> **JANGAN menebak path endpoint.** Hanya path yang tercantum di `GET /endpoints`\n> yang ada. Jika Anda mendapat 404, Anda menggunakan path yang salah.\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**Perbaikan:** Panggil `GET /endpoints` untuk melihat daftar endpoint yang\nvalid. Bandingkan URL Anda dengan daftar tersebut karakter per karakter.\n\n### 409 Conflict\n\nPermintaan berkonflik dengan kondisi yang ada. Penyebab umum:\n\n- Mencoba mendaftar dengan email yang sudah ada\n- URL webhook duplikat\n\n**Perbaikan:** Gunakan nilai yang berbeda, atau gunakan `PUT` untuk memperbarui sumber daya yang ada.\n\n### 429 Too Many Requests\n\nAnda mencapai rate limit. Hanya berlaku untuk autentikasi parameter query `?key=` (60/menit).\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\nHeader respons:\n\n```\nX-RateLimit-Limit: 60\nX-RateLimit-Remaining: 0\nRetry-After: 42\n```\n\n**Perbaikan:** Beralihlah ke header `Authorization: Bearer` (tanpa rate limit),\natau tunggu `Retry-After` detik.\n\n### 500 Internal Server Error\n\nError server. Ini seharusnya tidak terjadi — jika terjadi, itu adalah bug.\n\n**Perbaikan:**\n\n1. Coba lagi dengan exponential backoff (1d, 2d, 4d, 8d)\n2. Periksa `GET /health` untuk melihat apakah server aktif\n3. Jika berkelanjutan, laporkan error tersebut\n\n### 503 Service Unavailable\n\nServer sementara tidak tersedia (mis. selama deployment, migrasi database).\n\n**Perbaikan:** Tunggu dan coba lagi. Periksa `GET /health`.\n\n## Pola Pemulihan\n\n### Coba lagi dengan 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### Penanganan error autentikasi\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## Skenario Error Umum\n\n### \"Mind Key fehlt oder ungültig\"\n\n- Anda lupa header `Authorization`\n- Anda menggunakan `?key=` tetapi key-nya salah\n- Anda menggunakan JWT di mana Mind Key diperlukan\n\n### \"Route not found\"\n\n- Anda menebak path yang tidak ada\n- Anda menggunakan kata kerja yang salah (mis. `GET /memory` vs `POST /memory`)\n- Periksa `GET /endpoints` untuk path yang valid\n\n### \"Rate limit exceeded\"\n\n- Anda menggunakan `?key=` dan melebihi 60 req/menit\n- Beralihlah ke header `Authorization: Bearer`\n\n## Langkah Berikutnya\n\n- [Autentikasi](/docs/getting-started/authentication)\n- [Ikhtisar API](/docs/api/overview)\n- [Rate Limits](/docs/api/rate-limits)\n","content_html":"

Errors & Error Handling

\n

Synapse menggunakan kode status HTTP standar dengan format respons error yang\nkonsisten. Halaman ini menjelaskan cara menafsirkan dan memulihkan diri dari\nerror.

\n

Format Respons Error

\n

Semua error mengembalikan JSON dengan struktur berikut:

\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
FieldDeskripsi
statusCodeKode status HTTP
errorNama status HTTP
messageDeskripsi error yang dapat dibaca manusia
docsURL ke dokumentasi terkait (jika tersedia)
\n

Kode Status HTTP

\n

200 OK

\n

Berhasil. Permintaan diproses dengan benar.

\n

201 Created

\n

Berhasil. Sumber daya baru dibuat (mis. POST /memory).

\n

204 No Content

\n

Berhasil. Tidak ada body yang dikembalikan (mis. DELETE /memory/:id).

\n

400 Bad Request

\n

Permintaan tidak valid. Penyebab umum:

\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}

Perbaikan: Periksa body permintaan terhadap dokumentasi API. Pastikan\nsemua field yang wajib ada dan memiliki nilai yang valid.

\n

401 Unauthorized

\n

Autentikasi gagal. Penyebab umum:

\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}

Perbaikan: Verifikasi token Anda. Lihat Autentikasi.

\n

403 Forbidden

\n

Anda terautentikasi tetapi tidak diizinkan melakukan tindakan ini. Penyebab umum:

\n\n

Perbaikan: Periksa apakah Anda menggunakan tipe token yang benar untuk endpoint ini.

\n

404 Not Found

\n

Path atau sumber daya yang diminta tidak ada.

\n
**JANGAN menebak path endpoint.** Hanya path yang tercantum di `GET /endpoints`\nyang ada. Jika Anda mendapat 404, Anda menggunakan path yang salah.
{\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}

Perbaikan: Panggil GET /endpoints untuk melihat daftar endpoint yang\nvalid. Bandingkan URL Anda dengan daftar tersebut karakter per karakter.

\n

409 Conflict

\n

Permintaan berkonflik dengan kondisi yang ada. Penyebab umum:

\n\n

Perbaikan: Gunakan nilai yang berbeda, atau gunakan PUT untuk memperbarui sumber daya yang ada.

\n

429 Too Many Requests

\n

Anda mencapai rate limit. Hanya berlaku untuk autentikasi parameter query ?key= (60/menit).

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

Header respons:

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

Perbaikan: Beralihlah ke header Authorization: Bearer (tanpa rate limit),\natau tunggu Retry-After detik.

\n

500 Internal Server Error

\n

Error server. Ini seharusnya tidak terjadi — jika terjadi, itu adalah bug.

\n

Perbaikan:

\n
    \n
  1. Coba lagi dengan exponential backoff (1d, 2d, 4d, 8d)
    2. \n
  2. Periksa GET /health untuk melihat apakah server aktif
    3. \n
  3. Jika berkelanjutan, laporkan error tersebut
    4. \n
\n

503 Service Unavailable

\n

Server sementara tidak tersedia (mis. selama deployment, migrasi database).

\n

Perbaikan: Tunggu dan coba lagi. Periksa GET /health.

\n

Pola Pemulihan

\n

Coba lagi dengan 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")

Penanganan error autentikasi

\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

Skenario Error Umum

\n

"Mind Key fehlt oder ungültig"

\n\n

"Route not found"

\n\n

"Rate limit exceeded"

\n\n

Langkah Berikutnya

\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"]}