API 레퍼런스
로그인
본문으로 건너뛰기

오류 코드

러너 API와 콘솔과 CLI가 돌려주는 모든 오류 코드를 HTTP 상태, 다시 시도 가능 여부, 뜻과 함께 정리합니다

러너 API의 모든 오류는 같은 봉투로 옵니다, code로 분기하고 retryable이 true면 retry_after_s 뒤에 같은 요청을 다시 보냅니다

{
  "error": {
    "code": "workspace_spend_limit",
    "message": "Workspace monthly spend limit reached",
    "retryable": false,
    "retry_after_s": null,
    "fault": "payment",
    "request_id": "req_7Hq3Zk9Lm2",
    "docs_url": "https://xenoci.com/docs/errors#workspace_spend_limit",
    "details": { "limit_usd": "100.000000", "spent_usd": "100.039600", "resets_at": "2026-11-01T00:00:00Z" }
  }
}

fault는 client(요청 쪽), payment(잔액이나 한도), platform(XenoCI 쪽)입니다, request_id는 응답 헤더 X-Request-Id와 같고 문의할 때 알려 주세요

요청과 인증

코드HTTP다시 시도뜻
invalid_request400아니오본문이나 쿼리가 검증에 실패, details.fields에 문제 필드
invalid_amount400아니오충전 usd가 정수가 아니거나 범위(5 이상, 직접 입력 최대 이하) 밖
invalid_login400아니오로그인 링크나 코드, 가입 토큰이 틀리거나 만료, 사용됨
email_required400아니오Google이 이메일을 주지 않음
api_key_required401아니오Authorization: Bearer 헤더 없음
invalid_api_key401아니오모르는 키, 폐기, 만료, 체크섬 불일치, 보관된 워크스페이스의 키, 옛 xeno_ 키
api_key_revoked_leaked401아니오공개 유출로 자동 폐기된 키, 새 키 발급
session_required401아니오콘솔 엔드포인트에 세션 쿠키 없음
invalid_signature401아니오GitHub 시크릿 스캐닝 서명 검증 실패
insufficient_permission403아니오역할이나 키 권한이 부족, read 키의 쓰기 요청, 같은 출처가 아닌 쿠키 요청
console_only403아니오콘솔 세션 전용 엔드포인트를 API 키로 호출
workspace_archived403아니오보관된 워크스페이스, 새 잡과 업로드와 키 발급 거절
account_disabled403아니오비활성화된 계정
not_found404아니오자원이 없거나 이 호출자에게 보이지 않음, 러너 API가 꺼져 있을 때도 이 코드

상태 충돌

코드HTTP다시 시도뜻
conflict409아니오자원 상태가 요청을 허용하지 않음(끝난 잡 취소, 이미 폐기된 키, 같은 이름의 레시피, 이미 멤버), 다시 읽고 시도
idempotency_conflict409아니오같은 Idempotency-Key를 다른 본문으로 재사용
last_owner409아니오조직에 소유자가 없어지는 변경
default_workspace_protected409아니오기본 워크스페이스 보관 시도
google_mismatch409아니오이 이메일 계정에 이미 다른 Google 계정이 연결됨
invite_expired410아니오초대가 만료, 취소, 또는 이미 수락됨

잔액과 한도

코드HTTP다시 시도뜻푸는 방법
insufficient_credit402아니오사용 가능 잔액이 1분 요금보다 적음, details.topup_url소유자나 관리자가 충전
credit_exhausted402아니오실행 중이던 잡이 잔액 소진으로 분 경계에서 중단, HTTP 응답이 아니라 잡의 end_reason과 error.code충전 뒤 다시 제출
workspace_spend_limit402아니오워크스페이스 월 지출 한도 도달, details.limit_*, spent_*, resets_at한도 올리기
tier_monthly_limit402아니오티어 월 사용 한도 도달, details.tier, limit_*, used_*, resets_at다음 달 1일 00:00 UTC 또는 티어 상향
tier_concurrency_limit429가능동시 실행 한도에 닿았고 대기열도 가득, details.running, queued, max_queued, retry_after_s 60기다렸다 재시도
rate_limited429가능요청이 너무 많음, 지금은 로그인 메일 요청에만 적용retry_after_s 뒤 재시도

결제

코드HTTP다시 시도뜻
payment_amount_mismatch409아니오PortOne 결제의 금액, 통화, 상점이 주문과 다름, 적립 없음
payment_reference_reused409아니오이 paymentId가 이미 다른 주문에 묶임
payment_not_paid409가능PortOne이 아직 결제 완료로 보고하지 않음, 주문 상태를 다시 조회
topup_expired409아니오주문이 60분 대기 기간을 넘김, 새 주문
withdrawal_window_closed409아니오7일 청약철회 기간이 지남
fx_rate_unavailable503가능오늘의 고정 환율이 아직 없음, 충전이 잠시 닫힘
payments_unavailable503가능이 환경에서 충전이 꺼져 있음

플랫폼

코드HTTP다시 시도뜻
capacity_unavailable503가능맥 풀 용량이 없음, 잡을 받지 않았음, retry_after_s 60
login_unavailable503가능서버에 Google 로그인이 설정되지 않음
mail_unavailable503가능로그인이나 초대 메일을 보낼 수 없음
internal_error500가능예상하지 못한 오류, 반복되면 request_id와 함께 문의

결과물 전송(맥 호스트 전용)

코드HTTP뜻
unauthorized401잡 전용 토큰이 없거나 만료
artifact_offset_mismatch409결과물 조각의 오프셋이 이어지지 않음
artifact_checksum_mismatch409결과물 SHA-256 불일치
artifacts_too_large413결과물 합계가 2 GiB를 넘음

잡의 종료 이유와 오류 코드

잡 응답의 end_reason과 error.code는 HTTP 오류와 별개입니다

end_reason뜻error.code
succeeded스크립트 종료 코드 0
failed스크립트 종료 코드 0이 아님, 또는 대기 중 승인 재검사 실패workspace_spend_limit, tier_monthly_limit, workspace_archived
cancelled취소
timed_outtimeout_minutes 초과
credit_exhausted잔액 소진으로 분 경계에서 중단, 또는 대기 중 잔액 부족credit_exhausted, insufficient_credit
platform_errorVM 준비 두 번 실패, 러너 장애, 서버 재시작, 과금 없음internal_error

CLI와 MCP

어디값뜻
CLI 종료 코드잡의 종료 코드xenocast build가 기다린 잡의 스크립트 종료 코드
CLI 종료 코드3잔액 부족이나 한도 초과(insufficient_credit, credit_exhausted, workspace_spend_limit, tier_monthly_limit, tier_concurrency_limit), 충전 링크를 한 줄로 안내
CLI 오류invalid_api_key_formatXENOCI_API_KEY 값이 xci_live_ 형식이 아님
CLI 오류runner2_unsupportedAPI 키 모드에서 쓸 수 없는 옛 명령
MCPapi_key_requiredMCP 서버 환경에 키가 없음, xenocast config set api-key
MCPunknown_argument도구에 없는 인자

--json으로 실행한 CLI는 오류도 {"error":{...}} JSON 하나로 출력합니다

다음 단계