--- title: 오류와 재시도 description: HTTP 오류, 요청 제한, 수정 작업의 안전한 재시도 처리. --- # 오류와 재시도 API 오류는 HTTP 상태 코드와 JSON 본문으로 반환됩니다. ```json { "message": "피드백을 찾을 수 없습니다.", "statusCode": 404 } ``` 위 예시는 `Accept-Language: ko` 요청입니다. `message`는 표시용이며 언어에 따라 바뀝니다. 필드 검증 오류에서는 `title: ...; issueIds: ...`처럼 필드 경로가 포함될 수 있습니다. 현재 별도의 고정 문자열 오류 코드는 제공하지 않습니다. ## 상태 코드별 처리 | 상태 | 대표 원인 | 처리 | | ----- | ----------------------------------------------------------------------- | -------------------------------- | | `400` | UUID·필드·쿼리·PR URL 형식 오류, 같은 앱에 속하지 않는 피드백 연결 | 입력을 고친 후 다시 요청 | | `401` | 세션 없음, 에이전트 토큰 만료·철회·잘못된 형식, 토큰 관리에 Bearer 사용 | 인증 방식과 토큰을 확인 | | `403` | 앱 소유자 아님, 다른 앱의 토큰, 권한 부족, 허용되지 않은 Origin | 앱·권한·호출 출처 확인 | | `404` | 해당 앱의 피드백·작업·토큰을 찾을 수 없음 | ID와 앱을 다시 조회 | | `409` | 같은 요청 ID에 다른 생성 내용, 작업에 이미 다른 PR 연결 | 기존 작업을 조회하고 의도 확인 | | `413` | JSON 본문이 64 KiB 제한 초과 | 본문 크기를 줄임 | | `429` | 요청 빈도 초과 | `Retry-After`의 초 수만큼 기다림 | | `500` | 서버 처리 실패 | 잠시 뒤 제한적으로 재시도 | 인증과 Origin 검사 순서에 따라 같은 잘못된 요청도 먼저 발견한 오류가 반환됩니다. 예를 들어 Origin 없이 보낸 잘못된 Bearer 변경 요청은 토큰 검사 전에 `403`일 수 있습니다. ## 요청 제한 기본 서버 설정에서 자동화 경로는 IP별 1분당 120회입니다. 피드백, 수정 작업, 토큰 관리 요청이 같은 제한을 공유하므로 앱이나 토큰을 바꿔도 같은 IP의 호출량에 합산됩니다. 제한 카운터는 현재 API 프로세스 단위로 관리합니다. 실제 배포의 프록시나 운영 설정에 따라 추가 제한이 적용될 수 있습니다. `429` 응답은 다음과 같이 남은 대기 시간을 초로 알려 줍니다. ```http HTTP/1.1 429 Too Many Requests Retry-After: 28 Content-Type: application/json ``` 목록을 반복 폴링할 때는 호출 간격을 두고 한 번에 필요한 페이지를 요청하세요. 짧은 간격으로 같은 요청을 반복하지 마세요. ## 응답을 받지 못한 경우 네트워크 연결이 끊기거나 클라이언트 타임아웃이 나도 서버에서 작업을 마쳤을 수 있습니다. API별 재시도 규칙을 적용하세요. | 동작 | 재시도 규칙 | | -------------------------- | ------------------------------------------------- | | 피드백·수정 작업·토큰 조회 | 같은 요청 재시도 가능 | | 수정 작업 생성 | 같은 `clientRequestId`와 같은 본문 유지 | | PR 연결 | 같은 작업 ID와 같은 PR URL 유지 | | 토큰 철회 | 같은 토큰 ID로 재시도 가능 | | 토큰 발급 | 자동 재시도하지 않음. 반복하면 별도 토큰이 발급됨 | 수정 작업 생성의 멱등성 키는 JSON의 `clientRequestId`입니다. `Idempotency-Key` 헤더는 제공하지 않습니다. 같은 앱·생성자·키로 다른 내용을 보내면 `409`이므로, 요청 ID를 생성한 뒤 결과를 확인할 때까지 본문과 함께 보관하세요. `429`의 `Retry-After`를 우선 따르며, 일시적인 서버·네트워크 오류에는 지수 백오프와 임의 지연을 적용해 재시도 횟수를 제한하세요. `400`, `401`, `403`, `404`, `409`는 원인을 해결하기 전까지 반복 요청하지 않습니다. ## 자주 만나는 문제 ### 같은 계정의 다른 앱에서 403 에이전트 토큰은 앱 하나에 묶입니다. 대상 앱의 토큰을 별도로 발급하고 `OPENTESTER_APP_ID`도 일치시키세요. ### 쓰기 권한은 있는데 조회가 실패함 Scope는 서로 독립적입니다. 피드백 조회에는 `feedback:read`, 수정 작업 조회에는 `work-items:read`가 필요합니다. ### docs 도메인의 요청이 실패함 문서 사이트는 정적 문서입니다. API 기본 주소는 서비스 운영자가 제공한 별도 주소를 사용하고, 토큰 관리 같은 웹 세션 요청은 로그인한 콘솔의 Origin에서 실행하세요. [인증과 권한](/api/authentication)을 참고하세요. ### PR이 연결됐지만 피드백이 아직 open임 정상 동작입니다. PR 연결은 작업에 URL을 저장합니다. 피드백 검토와 처리 상태 변경은 개발자 콘솔에서 별도로 수행합니다.