테마
MCP 오류·제한·재시도
실패한 단계와 고정 코드를 먼저 확인합니다. 연결 문제는 아래 오류 계층, 파일 처리 문제는 자료 제한, 저장·원격 실행의 불명확한 결과는 실행 재시도를 참고하세요. 첫 조회와 파일 준비에는 단계별 예상 결과가 있습니다.
오류 계층
OAuth endpoint의 오류, MCP 접속의 HTTP 오류, MCP 도구의 isError 결과를 구분합니다. 도구 실패의 고정 코드는 structuredContent.error에서 확인하며 HTTP 상태와 일대일로 연결하지 않습니다. 오류 문장이나 고객 원문을 파싱해 권한·재시도 조건을 결정하지 않습니다.
토큰 endpoint의 invalid_grant 등 OAuth 오류는 일반적으로 HTTP 400과 JSON error로 반환됩니다. 만료·폐기된 code/refresh token은 갱신이나 재연결 여부를 확인합니다. 동의 과정의 access_denied는 callback의 error로 전달될 수 있으므로 HTTP 403만으로 판단하지 않습니다.
| 응답·코드 | 처리 |
|---|---|
MCP 접속 HTTP 401 / invalid_token | 토큰의 대상·만료·폐기를 확인하고 필요한 경우 갱신·재연결 |
도구 invalid_token, invalid_grant | 토큰·승인 상태를 확인하고 필요한 경우 재연결 |
도구 invalid_scope, access_denied | 프로그램 허용 목록·이번 동의·역할·조직·그룹 확인. 목록 밖이면 새 프로그램 등록·설정 교체, 목록 안이면 필요한 범위로 재로그인·동의 |
input_invalid, unprocessable_input | schema·버전·입력 항목을 수정 |
review_required | 현재 데이터로 검토를 다시 준비하고 변경 내용을 확인 |
rate_limit_exceeded | 동시에 보내는 요청을 줄이고 제한된 횟수로 지연 재시도 |
payload_too_large, output_size_exceeded | 파일·작업을 나누고 지원 응답 형식 확인 |
request_cancelled | 이미 발생한 저장 여부는 같은 실행 키와 조회로 확인 |
request_failed, configuration_required | 프로그램의 입력·환경을 확인하고 관리자에게 고정 코드·시각·도구 이름 전달 |
| HTTP 404 | 해당 환경의 MCP 활성화·접속 경로 확인 |
| GET MCP의 HTTP 405 | POST 전용 계약. 도구 호출은 MCP 전송 라이브러리 사용 |
자료 제한
| 대상 | 현재 한도 |
|---|---|
| CSV/XLSX 업로드 | 최대 5개, 디코딩 파일 합계 7 MiB |
| 전체 파일 파싱 | 50,000셀 |
| 정규화 원본·MCP 응답 | 각각 10 MiB |
| MCP HTTP 요청 본문 | 10 MiB |
| 요청·응답 시간 | 요청 30초·응답 60초. 클라이언트·프록시의 더 짧은 제한도 적용 |
| 템플릿·recipe 저장 | 1 MiB |
| 요청 예산 | read 분당 60회, analyze 5회, prepare 10회. 도구별 입력 상한 별도 |
파일 전체 파싱 제한은 업로드 후 영역 선택으로 우회할 수 없습니다. 식별 관계를 유지해 파일을 나누고, 페이지·행·선택 상한은 현재 inputSchema에서 확인합니다. 프로그램의 업무 처리 비용과 모델 추론 비용은 별개입니다.
로컬 파일 평가·PDF·이미지 추출은 별도 도구입니다. 원본·페이지·픽셀·추출 크기·엔진·언어 조건은 해당 페이지의 로컬 한도를 확인하세요. CLI 오류는 MCP structuredContent.error와 구분합니다.
정식 등록 배치는 1~10개의 기존 개별 승인 검토를 받습니다. 항목/단계는 한 호출에 하나만 선택하고 schema에 없는 필드·중복 검토·다른 생성 순서를 같은 키로 보내면 거절합니다. 배치 조회도 원래 owner/client/grant의 현재 권한과 products:register가 필요합니다. 한도의 기준은 접속 릴리스의 tools/list와 입력 schema입니다.
실행 재시도
조회와 저장 실행을 구분합니다. 초안 생성·수정의 응답이 불명확하면 같은 검토 내용과 재시도 키로 결과를 확인합니다. 요청마다 새 키를 만들면 새 작업으로 처리될 수 있습니다. 읽기 재시도에도 횟수와 대기 상한을 둡니다.
불변 BOM·PCF 게시의 마지막 DTR 단계만 불확실한 경우에는 원래 조회 도구가 제한된 원격 GET과 수락 영수증 동기화를 수행할 수 있습니다. 정확한 항목·전체 본문 일치가 필요하며 조회 안에서 게시나 새 POST는 하지 않습니다. 마지막 DTR 단계 복구에 따라 최종 게시는 별도로 실행합니다.
원격 조회의 시간 초과는 등록 실패나 자원 부재를 뜻하지 않습니다. 중간 조회 경로가 빈 필드를 제거한 응답도 원래 본문과의 일치 증거로 사용할 수 없습니다. 원래 검토와 실행 키를 보존하고, 관리자에게 발생 시각·도구 이름·고정 오류 코드를 전달해 원격 접수 기록과 통신 경로를 대조합니다.
배치의 resume은 전송되지 않은 것으로 확인된 재시도 가능 실패만 로컬 상태로 되돌립니다. 별도 execute가 필요하고 in_flight/needs_reconciliation에는 사용할 수 없습니다. 취소는 새 단계와 로컬 게시를 막으며 이미 시작했거나 완료한 외부 효과를 되돌리지 않습니다. 새 배치·새 키·기존 단일 등록 도구로 불확실 전송이나 취소를 우회하지 않습니다.
원격 ID 없는 지원 EDC/정식 등록 step의 불확실 결과는 현재 소유자의 운영 인수 API에 기록할 수 있습니다. 복구 route는 로컬 기록만 읽거나 추가하고 provider 조회·재전송·성공 확정을 하지 않습니다. 요청은 4096바이트, case당 첫 접수 포함 100개 event, 목록 최대 100건·상세 event 20건 단위이며 자유 텍스트·원문 업로드·remote ID·client 시각은 받지 않습니다. expectedRevision 충돌은 새 상태를 읽고 판단하며 서버가 임의 재시도하지 않습니다.
별도 정식 등록 DTR 수락 확인은 정상 소유자 명령으로 제공자 GET만 수행합니다. 추가 필드·배열 순서를 포함한 본문 전체 불일치, 회수·만료·자료/키/설정 변경, 기존 시도와 맞지 않는 증거는 수락하지 않습니다. unconfirmed를 실패 후 안전한 재전송 가능 상태로 해석하지 않습니다. 외부 PC 직결 HTML 404는 내부 네트워크 진입 제한일 수도 있으므로 실제 자원 부재와 구분합니다.
| 운영 인수 오류·표시 | 처리 |
|---|---|
unsupported_source, recovery_source_not_eligible | 지원 journal과 정확한 step·remote ID 부재·불확실 전이 여부 확인. 다른 domain/A2A task를 임의 연결하지 않음 |
recovery_revision_conflict, recovery_idempotency_conflict | 현재 revision·원래 입력을 확인. 새 키로 원래 provider POST를 재전송하지 않음 |
recovery_source_changed | current freshness를 확인. 이력 조회가 필요하면 view=history를 명시하되 현재 owner/source 소유 검사는 유지 |
recovery_case_not_found, access_denied | 현재 조직·그룹·source 소유·역할 확인. 타 조직 ID 존재 여부를 추정하지 않음 |
canonicalOutcome:unknown, outcomeMeaning:at_intake | 접수 당시 기록. 현재 사실 결과·실행 권한은 원래 journal에서 별도 확인 |
worker health unknown/stale | 마지막 기록의 부재/지연. backlog 0·현재 작업 정상 완료로 간주하지 않음 |
복구 기능은 접속 릴리스에 필요한 schema와 코드가 배포돼 있어야 합니다. current/history의 자료 freshness와 현재 읽기 자격을 각각 확인합니다. history 조회로 구독·역할·소유 범위를 우회하거나 원래 OAuth 동의·웹 승인·실행 권한을 되살릴 수 없습니다.
신고 시 access/refresh token·원본 파일·고객 제품 내용을 일반 채팅이나 로그에 붙이지 않습니다. 승인된 지원 절차로 필요한 자료를 전달합니다.
Codex 로그인에서 invalid_request
등록한 HTTPS 콜백과 Codex 설정이 일치하는지 확인합니다. 메타데이터가 제공하는 resource에 oauth_resource를 수동 추가해 resource가 중복 전송되는지 확인합니다. Codex 연결 예제처럼 자동 탐색을 사용합니다. 인증 URL을 지원 요청에 그대로 붙이지 말고 클라이언트 버전·고정 오류 코드·파라미터의 중복 여부만 전달합니다.
문제가 계속되면 관리자에게 발생 시각·클라이언트 종류/버전·도구 이름·고정 오류 코드만 먼저 전달합니다. 토큰이나 전체 인증 URL을 공유하지 않습니다.
복합 업무 오류
workflow_revision_conflict는 최신 metadata를 다시 읽고 현재 nextAction을 확인합니다. workflow_source_changed·workflow_reservation_changed·workflow_idempotency_conflict는 원래 입력·검토 결합을 다시 확인하며 새 키로 외부 요청을 우회하지 않습니다. workflow_predecessor_incomplete는 선행 업무의 실제 완료를 기다립니다. workflow_action_blocked는 원래 승인·불확실 결과를 조사하고, workflow_cancelled는 후속 실행을 중단합니다. workflow_event_limit는 기록 상한으로 새 metadata 동작이 막힌 상태이며 취소·사실 조회는 유지됩니다. workflow_unavailable은 원래 기록을 읽을 수 없는 상태이며 완료·미전송 증거가 아닙니다.