Errors & Error Handling

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

Format Respons Error

Semua error mengembalikan JSON dengan struktur berikut:

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

Kode Status HTTP

200 OK

Berhasil. Permintaan diproses dengan benar.

201 Created

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

204 No Content

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

400 Bad Request

Permintaan tidak valid. Penyebab umum:

• Field JSON yang wajib tidak ada
• Sintaks JSON tidak valid
• Nilai enum tidak valid (mis. kategori salah)

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

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

401 Unauthorized

Autentikasi gagal. Penyebab umum:

• Header Authorization tidak ada
• Mind Key atau JWT tidak valid
• Menggunakan Mind Key di mana JWT diperlukan (atau sebaliknya)

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

Perbaikan: Verifikasi token Anda. Lihat Autentikasi.

403 Forbidden

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

• Mencoba menghapus mind pengguna lain
• Mencoba memverifikasi memori dengan Mind Key (memerlukan JWT)
• Mind dinonaktifkan

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

404 Not Found

Path atau sumber daya yang diminta tidak ada.

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Route GET /memory/list not found",
  "docs": "https://synapse.schaefer.zone/docs/api/errors"
}

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

409 Conflict

Permintaan berkonflik dengan kondisi yang ada. Penyebab umum:

• Mencoba mendaftar dengan email yang sudah ada
• URL webhook duplikat

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

429 Too Many Requests

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

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

Header respons:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
Retry-After: 42

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

500 Internal Server Error

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

Perbaikan:

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

503 Service Unavailable

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

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

Pola Pemulihan

Coba lagi dengan exponential backoff

import time
import requests

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

Penanganan error autentikasi

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

Skenario Error Umum

"Mind Key fehlt oder ungültig"

• Anda lupa header Authorization
• Anda menggunakan ?key= tetapi key-nya salah
• Anda menggunakan JWT di mana Mind Key diperlukan

"Route not found"

• Anda menebak path yang tidak ada
• Anda menggunakan kata kerja yang salah (mis. GET /memory vs POST /memory)
• Periksa GET /endpoints untuk path yang valid

"Rate limit exceeded"

• Anda menggunakan ?key= dan melebihi 60 req/menit
• Beralihlah ke header Authorization: Bearer

Langkah Berikutnya

• Autentikasi
• Ikhtisar API
• Rate Limits