# 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:

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

| Field | Deskripsi |
|-------|-------------|
| `statusCode` | Kode status HTTP |
| `error` | Nama status HTTP |
| `message` | Deskripsi error yang dapat dibaca manusia |
| `docs` | URL ke dokumentasi terkait (jika tersedia) |

## 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)

```json
{
  "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)

```json
{
  "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](/docs/getting-started/authentication).

### 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.

> [!CRITICAL]
> **JANGAN menebak path endpoint.** Hanya path yang tercantum di `GET /endpoints`
> yang ada. Jika Anda mendapat 404, Anda menggunakan path yang salah.

```json
{
  "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).

```json
{
  "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

```python
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

```python
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](/docs/getting-started/authentication)
- [Ikhtisar API](/docs/api/overview)
- [Rate Limits](/docs/api/rate-limits)