API 오류

API는 표준 HTTP 상태 코드와 통합 응답 본문으로 오류를 알립니다. 성공 응답은 래퍼 없이 직접 데이터를 반환합니다.

오류 형식

오류 발생 시 응답 본문은 사람이 읽을 수 있는 메시지가 담긴 error 필드 하나로 이루어진 JSON 객체입니다:

{"error":"reaction not found"}

우선적으로 HTTP 상태 코드를 기준으로 삼고, error 텍스트는 로그와 사용자 안내에 활용하세요.

상태 코드

  • 200 OK — 요청 성공, 본문에 데이터.
  • 201 Created — 새 리소스 생성됨 (일부 POST 엔드포인트).
  • 204 No Content — 본문 없이 성공 (일부 삭제).
  • 400 Bad Request — 잘못된 본문 또는 요청 매개변수.
  • 401 Unauthorized — 토큰 없음, 잘못되었거나 만료됨; 또는 경로가 개인 토큰으로 접근 불가.
  • 402 Payment Required — 액션이 요금제 또는 할당량에 걸림 (예: 자체 미디어 저장소는 premium 필요).
  • 403 Forbidden — 토큰에 이 경로에 필요한 접근 범위가 없음.
  • 404 Not Found — 리소스를 찾을 수 없거나 귀하의 것이 아님.
  • 409 Conflict — 상태 충돌 (예: 고유 값 중복).
  • 422 Unprocessable Entity — 본문이 구문적으로 유효하지만 도메인 유효성 검사 실패.
  • 429 Too Many Requests — 요청 한도 초과 (한도 참조).
  • 500 Internal Server Error — 내부 서버 오류; 나중에 다시 시도하세요.

처리 방법

2xx 코드를 성공으로 간주하세요. 401/403은 토큰과 접근 범위를 확인하세요. 4xx (429 제외)는 요청을 수정하지 않고 재시도하지 마세요. 429와 5xx는 지수 백오프로 재시도가 적합합니다.

다음 단계