문제 해결

증상별 원인·확인·해결입니다.

연결이 안 됩니다

원인: 키가 만료됐거나 폐기됐거나, 요청한 기능을 허용하지 않았습니다.
확인: 연결 화면의 키 목록에서 상태와 허용 기능을 봅니다. 응답이 401이면 키 문제입니다.
해결: 필요한 기능을 허용한 새 키를 만들고 클라이언트의 환경변수를 바꿉니다. 인증 헤더는 하나만 보내세요.

일부 기능이 안 보입니다

원인: 캐릭터챗 저작은 팀 전용이고, 만화 저작은 만화 작업실이 열린 환경에서만 있습니다.
확인: 도구와 안전장치의 기능 표.
해결: 해당 환경과 계정에서 키를 만듭니다.

승인 대기에서 멈춥니다

원인: 웹 승인이 필요한 호출입니다. 에이전트는 승인할 수 없습니다.
확인: 영수증에 든 승인 링크.
해결: 링크를 열어 10분 안에 승인한 뒤 같은 입력으로 같은 도구를 다시 부릅니다. 입력이 바뀌면 승인이 무효입니다.

체리가 부족하다고 나옵니다

원인: 견적 금액이 잔액을 넘습니다. 오류는 INSUFFICIENT_CHERRY(402)이고, 필요한 양과 잔액이 함께 옵니다.
확인: 응답의 required_cherry, balance_cherry.
해결: 충전한 뒤 다시 요청합니다.

한도에 걸렸습니다

429에는 두 종류가 있고 error.code로 구분합니다.

코드	뜻	해결
`RATE_LIMITED`	시간당 호출 한도	`Retry-After`만큼 기다린 뒤 다시 보냅니다.
`SPEND_LIMIT_EXCEEDED`	키에 건 지출 한도	기간이 바뀔 때까지 기다리거나 연결 화면에서 한도를 올립니다.

같은 요청이 409로 거절됩니다

원인: 같은 멱등 키를 다른 본문에 다시 썼습니다(conflict_reason: idempotency_key_reused).
해결: 같은 요청의 재전송이면 본문을 똑같이 보내고, 새 요청이면 새 키를 씁니다.

도구 응답에 진단(`diagnostics`)이 있습니다

MCP 도구는 실패해도 오류 봉투 대신 diagnostics 배열(level, code, loc, message)로 알립니다. level이 error이면 그 호출은 실패한 것이고, warning이면 성공했지만 확인할 것이 있다는 뜻입니다. 코드는 아래 표로 대응합니다. 공통 코드는 모든 서버에서 나옵니다.

코드	뜻	해야 할 일
`invalid_input`	입력 형식 오류	`loc`가 가리키는 필드를 고쳐 다시 보냅니다. 같은 입력의 재시도는 소용없습니다.
`unauthorized`	키가 없거나 만료	사용자에게 키 재발급을 안내합니다.
`forbidden`	이 서버나 기능이 허용하지 않는 요청	돌려서 시도하지 말고 사용자에게 알립니다.
`not_found`	내 것이 아니거나 없는 대상	둘을 구분해 알려 주지 않습니다. id를 다시 확인합니다.
`conflict`	상태 충돌	최신 상태를 다시 읽고 판단합니다.
`insufficient_cherry`	체리 부족	제출하지 말고 잔액과 견적을 사용자에게 보여 줍니다.
`rate_limited`	호출 한도 초과	아래 "한도 종류"를 봅니다.
`unavailable`	일시적으로 처리할 수 없음	잠시 뒤 같은 요청을 다시 보냅니다. 체리를 쓰는 요청은 같은 `idempotencyKey`를 씁니다.
`internal`	서버 오류	같은 요청을 한 번만 다시 보내고, 계속되면 사용자에게 알립니다.
`spend_limit_exceeded`	키의 지출 한도 초과	제출하지 말고 `details`의 한도와 사용량, `retry_after_seconds`를 사용자에게 알립니다.
`price_unpublished`	가격이 공표되지 않은 모델	제출하지 말고 `details.price_reason`을 알린 뒤 가격이 공표된 모델을 고릅니다.
`collab_state_invalid`	협업 문서에 적용하면 형식이 맞지 않는 변경	같은 변경을 다시 보내지 말고 문서를 새로 읽어 다시 만듭니다.
`policy_reacceptance_required`	결제 전에 다시 동의할 약관이 있음	결제를 진행하지 말고 사용자가 웹 화면에서 동의하게 안내합니다.

서버마다 더 나오는 코드는 다음과 같습니다.

코드	나오는 서버	해야 할 일
`section_not_found`	영상	없는 `sectionId`입니다. `sectionId` 없이 읽어 섹션 목록을 확인합니다.
`idempotency_key_unavailable`	영상, 웹소설	그 키로 만든 문서가 휴지통에 있습니다. 새 키를 씁니다.
`idempotent_replay_title_differs`	영상, 만화, 웹소설	경고입니다. 같은 키로 이미 다른 제목의 작품이 있습니다. 응답의 작품을 그대로 씁니다.
`response_too_large`	영상, 웹소설	읽기 응답이 64KiB 상한을 넘습니다. 영상은 `view`를 `outline`이나 `timeline`으로, 웹소설은 `episodeId`와 `sceneId`로 범위를 좁힙니다.
`unpriced`	영상	컷 묶음 제안이 고른 모델·해상도·오디오 조합에 견적이 없습니다. 견적이 공표된 조합을 고릅니다.
`no_clips`	영상	묶을 컷이 없습니다. 응답 `skipped`의 사유를 확인합니다.
`asset_unavailable`	이미지 생성, 영상 생성	경고입니다. 결과 파일이 삭제돼 읽기 링크를 만들 수 없습니다. 다른 후보를 씁니다.

한도 종류

rate_limited 진단의 limit_kind가 어느 한도에 걸렸는지 알려 줍니다.

표면 호출 한도: surface_read, surface_write. 읽기와 쓰기를 따로 셉니다.
시간당 한도: hourly, video_hourly, enhance_hourly, audio_hourly, upscale_hourly, image_adjust_hourly, frame_extract_hourly, memo_write_hourly. retry_after_seconds만큼 기다리면 풀립니다.
기다려도 풀리지 않는 한도: 동시 실행(image_active, video_active, audio_active), 하루(image_daily), 한 요청에 묶는 호출 수(request_batch). retry_after_seconds가 없습니다. 진행 중인 작업이 끝나거나 요청을 줄여야 합니다.

기능별 시간당 호출 수는 도구와 안전장치에 있습니다.

CLI `doctor`가 실패합니다

원인: 주소나 토큰이 없거나 토큰 파일 권한이 넓습니다. 종료 코드는 6입니다.
확인: doctor 출력의 FAIL 줄.
해결: 인증대로 설정하고 chmod 600을 적용합니다.

문의할 때

요청 id(error.requestId, 응답 헤더 X-Request-Id)를 함께 알려 주세요. 키 값은 보내지 마세요.