개발자 문서
API, CLI 및 MCP 연결 문제 해결
자격 증명을 노출하거나 접수된 작업을 중복 생성하지 않고 로그인, 권한, 스키마, 업로드, 불확실한 쓰기 오류를 해결하세요.
Markdown으로 읽기SosoAPI 팀 검토 ·
잘못된 브라우저 또는 차단된 로컬 로그인
대기 중인 로그인을 중지하고 auth login --no-open을 실행하세요. 새로 출력된 URL을 원하는 브라우저 프로필에서 여세요. 접근 승인 전에 계정과 Workspace를 확인하고 같은 로그인 링크에는 프로필 하나만 사용하세요. 포트 8789가 사용 중이면 리스너를 확인하고 직접 시작한 로그인 프로세스일 때만 중지하세요.
npx sosoapi auth login --no-openlsof -nP -iTCP:8789 -sTCP:LISTEN401, 403 및 이용 불가 계정
401이면 현재 유효한 자격 증명으로 로그인했는지 확인하세요. 403이면 Workspace 역할, 선택 범위, 필수 기능을 확인하세요. auth status로 계정 이메일과 허용 자격 증명 유형을 확인하세요. 해당 작업에 필요한 경우에만 접근을 변경하세요. 도구 프로필 변경은 권한을 부여하지 않습니다.
소셜 계정을 별도로 확인하세요. 연결과 기능을 읽고 제공업체가 새 동의를 요구할 때만 재연결하세요. 내부 서비스 오류는 정상 연결을 다시 만들 이유가 아닙니다.
400 검증 및 버전 불일치
응답 본문과 검증 필드 경로를 읽으세요. 검증 오류에는 ZodError가, 핸들러 오류에는 error, message, code가 있을 수 있습니다. 요청과 설치 계약을 비교하고 필요하면 클라이언트 패키지를 업데이트하세요. 필수 값을 제거하거나 미지원 필터를 추가하지 말고 오류에 명시된 필드를 수정하세요.
npx sosoapi api contract --route /studio-api/scheduled-posts/409, 429, 5xx 또는 쓰기 시간 초과
409는 변경 전에 최신 리소스 버전과 가능한 작업을 읽으세요. 429는 Retry-After에 따라 기다리고 동시 실행 수를 줄이세요. 쓰기가 시간 초과하거나 5xx를 반환하면 ID를 유지하고 먼저 기존 결과를 확인하세요. 연결 실패 전에 서버가 접수했을 수 있습니다.
해당 작업과 현재 상태가 허용할 때만 재시도하세요. 같은 페이로드에는 같은 키를 유지하고 불확실한 결과를 우회할 대체 항목을 만들지 마세요. 재시도 전에 인증 오류를 해결하세요. 백그라운드 작업이 대기 중이어도 상태에 확인할 실행 오류가 이미 있을 수 있습니다.
업로드 또는 도구 검색 문제
로컬 업로드는 작업 디렉터리, 임시 폴더, Pictures/Movies/Videos 또는 SOSOAPI_UPLOAD_ROOTS 폴더의 지원 미디어를 최대 500 MiB까지 허용합니다. 점으로 시작하는 폴더와 루트 밖으로 나가는 심볼릭 링크는 거부합니다. 홈 디렉터리 전체 대신 필요한 미디어 폴더만 추가하세요. HTTP 연결은 로컬 파일을 읽을 수 없습니다.
도구가 없으면 클라이언트를 재연결하고 프로필과 연결 유형을 참조와 비교하세요. 현재 대화에 도구가 로드되었는지 확인하세요. 저장된 서버 이름만으로는 확인되지 않습니다.
유용한 진단 정보를 안전하게 공유
작업 이름, 시간, HTTP 상태, 안전한 오류 코드 및 가능한 request_id 또는 x-request-id를 공유하세요. CLI 버전과 로컬/원격 MCP 여부도 포함하세요. 토큰, 쿠키, 인증 링크, 서명 미디어 URL, 고객 콘텐츠, 비공개 ID는 제거하세요. 자격 증명 파일이나 전체 응답 대신 관련 오류만 공유하세요.