오류 및 오류 처리

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

오류 응답 형식

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

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

HTTP 상태 코드

200 OK

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

201 Created

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

204 No Content

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

400 Bad Request

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

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

{
  "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 사용 (또는 그 반대)

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

해결: 토큰을 확인하십시오. Authentication을 참조하십시오.

403 Forbidden

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

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

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

404 Not Found

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

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

{
  "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를 확인하십시오.

복구 패턴

지수 백오프 재시도

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

인증 오류 처리

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
• API 개요
• 속도 제한