# 오류 및 오류 처리
SUMMARY: HTTP 상태 코드, 오류 응답 형식, 그리고 일반적인 오류로부터 복구하는 방법.

KEY CONTEXT:
Error format: { statusCode, error, message, docs? }
Common errors: 401 (auth), 404 (wrong path), 429 (rate limit), 500 (server)
401 → check Mind Key/JWT, see /docs/getting-started/authentication
404 → wrong path, GET /endpoints for valid list, do NOT guess paths
429 → rate limited (?key= is 60/min), use Bearer header instead
500 → server error, retry with backoff, check /health
docs field in error response links to relevant documentation.

오류 및 오류 처리
Synapse는 표준 HTTP 상태 코드와 일관된 오류 응답 형식을 사용합니다.
이 페이지에서는 오류를 해석하고 복구하는 방법을 설명합니다.
오류 응답 형식
모든 오류는 다음 구조의 JSON을 반환합니다:
[CODE BLOCK]
| 필드 | 설명 |
|-------|-------------|
|  | HTTP 상태 코드 |
|  | HTTP 상태 이름 |
|  | 사람이 읽을 수 있는 오류 설명 |
|  | 관련 문서 URL (해당되는 경우) |
HTTP 상태 코드
200 OK
성공입니다. 요청이 올바르게 처리되었습니다.
201 Created
성공입니다. 새 리소스가 생성되었습니다 (예: ).
204 No Content
성공입니다. 본문이 반환되지 않았습니다 (예: ).
400 Bad Request
요청이 잘못되었습니다. 일반적인 원인:
- 필수 JSON 필드 누락
- 잘못된 JSON 구문
- 잘못된 enum 값 (예: 잘못된 카테고리)
[CODE BLOCK]
해결: API 문서와 대조하여 요청 본문을 확인하십시오. 모든 필수 필드가
존재하고 유효한 값을 가지고 있는지 확인하십시오.
401 Unauthorized
인증에 실패했습니다. 일반적인 원인:
-  헤더 누락
- 잘못된 Mind Key 또는 JWT
- JWT가 필요한 곳에 Mind Key 사용 (또는 그 반대)
[CODE BLOCK]
해결: 토큰을 확인하십시오. Authentication을 참조하십시오.
403 Forbidden
인증은 되었지만 이 작업을 수행할 권한이 없습니다. 일반적인 원인:
- 다른 사용자의 마인드 삭제 시도
- Mind Key로 memory 검증 시도 (JWT 필요)
- 마인드가 비활성화됨
해결: 이 엔드포인트에 올바른 토큰 유형을 사용하고 있는지 확인하십시오.
404 Not Found
요청한 경로 또는 리소스가 존재하지 않습니다.
> [!CRITICAL]
> 엔드포인트 경로를 추측하지 마십시오. 에 나열된
> 경로만 존재합니다. 404를 받았다면 잘못된 경로를 사용한 것입니다.
[CODE BLOCK]
해결: 를 호출하여 유효한 엔드포인트 목록을
확인하십시오. URL을 목록과 글자 단위로 비교하십시오.
409 Conflict
요청이 기존 상태와 충돌합니다. 일반적인 원인:
- 이미 존재하는 이메일로 등록 시도
- 중복된 webhook URL
해결: 다른 값을 사용하거나, 을 사용하여 기존 리소스를
업데이트하십시오.
429 Too Many Requests
속도 제한에 도달했습니다.  쿼리 파라미터 인증에만 적용됩니다 (분당 60회).
[CODE BLOCK]
응답 헤더:
[CODE BLOCK]
해결:  헤더로 전환하거나 (속도 제한 없음),
초 동안 기다리십시오.
500 Internal Server Error
서버 오류입니다. 이런 일이 발생해서는 안 되며 — 발생한다면 버그입니다.
해결:
1. 지수 백오프로 재시도 (1초, 2초, 4초, 8초)
2. 를 확인하여 서버가 실행 중인지 확인
3. 지속되면 오류를 보고하십시오
503 Service Unavailable
서버가 일시적으로 중단되었습니다 (예: 배포 중, 데이터베이스 마이그레이션).
해결: 기다렸다가 재시도하십시오. 를 확인하십시오.
복구 패턴
지수 백오프 재시도
[CODE BLOCK]
인증 오류 처리
[CODE BLOCK]
일반적인 오류 시나리오
"Mind Key fehlt oder ungültig"
-  헤더를 잊음
- 를 사용했지만 키가 잘못됨
- Mind Key가 필요한 곳에 JWT를 사용 중
"Route not found"
- 존재하지 않는 경로를 추측함
- 동사를 잘못 사용함 (예:  vs )
- 에서 유효한 경로 확인
"Rate limit exceeded"
- 를 사용하여 분당 60회 초과
-  헤더로 전환
다음 단계
- Authentication
- API 개요
- 속도 제한