# 오류 및 오류 처리

Synapse는 표준 HTTP 상태 코드와 일관된 오류 응답 형식을 사용합니다.
이 페이지에서는 오류를 해석하고 복구하는 방법을 설명합니다.

## 오류 응답 형식

모든 오류는 다음 구조의 JSON을 반환합니다:

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

| 필드 | 설명 |
|-------|-------------|
| `statusCode` | HTTP 상태 코드 |
| `error` | HTTP 상태 이름 |
| `message` | 사람이 읽을 수 있는 오류 설명 |
| `docs` | 관련 문서 URL (해당되는 경우) |

## HTTP 상태 코드

### 200 OK

성공입니다. 요청이 올바르게 처리되었습니다.

### 201 Created

성공입니다. 새 리소스가 생성되었습니다 (예: `POST /memory`).

### 204 No Content

성공입니다. 본문이 반환되지 않았습니다 (예: `DELETE /memory/:id`).

### 400 Bad Request

요청이 잘못되었습니다. 일반적인 원인:

- 필수 JSON 필드 누락
- 잘못된 JSON 구문
- 잘못된 enum 값 (예: 잘못된 카테고리)

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

**해결:** API 문서와 대조하여 요청 본문을 확인하십시오. 모든 필수 필드가
존재하고 유효한 값을 가지고 있는지 확인하십시오.

### 401 Unauthorized

인증에 실패했습니다. 일반적인 원인:

- `Authorization` 헤더 누락
- 잘못된 Mind Key 또는 JWT
- JWT가 필요한 곳에 Mind Key 사용 (또는 그 반대)

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

**해결:** 토큰을 확인하십시오. [Authentication](/docs/getting-started/authentication)을 참조하십시오.

### 403 Forbidden

인증은 되었지만 이 작업을 수행할 권한이 없습니다. 일반적인 원인:

- 다른 사용자의 마인드 삭제 시도
- Mind Key로 memory 검증 시도 (JWT 필요)
- 마인드가 비활성화됨

**해결:** 이 엔드포인트에 올바른 토큰 유형을 사용하고 있는지 확인하십시오.

### 404 Not Found

요청한 경로 또는 리소스가 존재하지 않습니다.

> [!CRITICAL]
> **엔드포인트 경로를 추측하지 마십시오.** `GET /endpoints`에 나열된
> 경로만 존재합니다. 404를 받았다면 잘못된 경로를 사용한 것입니다.

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

**해결:** `GET /endpoints`를 호출하여 유효한 엔드포인트 목록을
확인하십시오. URL을 목록과 글자 단위로 비교하십시오.

### 409 Conflict

요청이 기존 상태와 충돌합니다. 일반적인 원인:

- 이미 존재하는 이메일로 등록 시도
- 중복된 webhook URL

**해결:** 다른 값을 사용하거나, `PUT`을 사용하여 기존 리소스를
업데이트하십시오.

### 429 Too Many Requests

속도 제한에 도달했습니다. `?key=` 쿼리 파라미터 인증에만 적용됩니다 (분당 60회).

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

응답 헤더:

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

**해결:** `Authorization: Bearer` 헤더로 전환하거나 (속도 제한 없음),
`Retry-After`초 동안 기다리십시오.

### 500 Internal Server Error

서버 오류입니다. 이런 일이 발생해서는 안 되며 — 발생한다면 버그입니다.

**해결:**

1. 지수 백오프로 재시도 (1초, 2초, 4초, 8초)
2. `GET /health`를 확인하여 서버가 실행 중인지 확인
3. 지속되면 오류를 보고하십시오

### 503 Service Unavailable

서버가 일시적으로 중단되었습니다 (예: 배포 중, 데이터베이스 마이그레이션).

**해결:** 기다렸다가 재시도하십시오. `GET /health`를 확인하십시오.

## 복구 패턴

### 지수 백오프 재시도

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

### 인증 오류 처리

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

## 일반적인 오류 시나리오

### "Mind Key fehlt oder ungültig"

- `Authorization` 헤더를 잊음
- `?key=`를 사용했지만 키가 잘못됨
- Mind Key가 필요한 곳에 JWT를 사용 중

### "Route not found"

- 존재하지 않는 경로를 추측함
- 동사를 잘못 사용함 (예: `GET /memory` vs `POST /memory`)
- `GET /endpoints`에서 유효한 경로 확인

### "Rate limit exceeded"

- `?key=`를 사용하여 분당 60회 초과
- `Authorization: Bearer` 헤더로 전환

## 다음 단계

- [Authentication](/docs/getting-started/authentication)
- [API 개요](/docs/api/overview)
- [속도 제한](/docs/api/rate-limits)