실패와 재시도
제출 거절, 스크립트 실패, 플랫폼 오류를 구분하고 각각 언제 어떻게 다시 보내면 되는지 설명합니다
실패는 세 종류입니다
제출 단계에서 거절된 요청, 스크립트가 0이 아닌 종료 코드로 끝난 잡, 그리고 플랫폼 책임으로 끝난 잡이고 다시 보내는 방법이 각각 다릅니다
1. 제출이 거절된 경우 (HTTP 4xx, 5xx)
POST /v1/jobs가 201이 아니면 잡은 만들어지지 않았고 과금도 없습니다
오류 봉투의 retryable과 retry_after_s가 재시도 가능 여부를 말해 줍니다
| 코드 | 다시 보내려면 |
|---|---|
invalid_request | details.fields의 필드를 고쳐서 다시 보냄 |
insufficient_credit | details.topup_url에서 충전한 뒤 다시 보냄 충전은 콘솔 로그인이 필요함 |
workspace_spend_limit | 소유자나 관리자가 콘솔 관리 → 워크스페이스에서 월 한도를 올리거나 details.resets_at(다음 달 1일 00:00 UTC) 이후 |
tier_monthly_limit | 다음 달 1일 00:00 UTC 또는 충전으로 티어가 오른 뒤 |
tier_concurrency_limit | Retry-After 헤더(60초) 뒤 다시 보냄 실행 중인 잡이 끝나면 대기열이 비움 |
capacity_unavailable | retry_after_s(60초) 뒤 다시 보냄 |
workspace_archived | 보관된 워크스페이스는 잡을 받지 않음 다른 워크스페이스의 키를 쓰기 |
재시도할 때는 처음 요청과 같은 Idempotency-Key를 보내세요
네트워크 오류로 응답을 못 받았더라도 24시간 안에 같은 키와 본문을 보내면 이미 만든 잡을 돌려주므로 잡이 두 번 생기지 않습니다
KEY=$(uuidgen)
curl -s https://xenoci.com/api/runner/v1/jobs \
-H "Authorization: Bearer $XENOCI_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $KEY" \
-d @job.jsonCLI와 MCP는 잡 제출마다 멱등 키를 자동으로 붙입니다
2. 스크립트가 실패한 경우 (failed)
스크립트의 종료 코드가 0이 아니면 잡은 failed이고 exit_code에 그 값이 들어갑니다
실행한 분은 과금됩니다
원인은 로그에 있습니다
CLI는 로그에서 첫 오류 줄 주변만 잘라 보여 줍니다
xenocast logs job_7Kp2QmX9bT4vR1sLwZ3n --failurexcodebuild의 error: 줄, ** BUILD FAILED **, fatal, Traceback 같은 패턴을 찾아 그 앞뒤 60줄을 냅니다
스크립트는 bash -eo pipefail로 돌기 때문에 중간 명령 하나가 실패해도 그 자리에서 멈춥니다
실패해도 계속하려면 그 명령 뒤에 || true를 붙이세요
같은 잡을 다시 돌리는 전용 API는 없습니다
같은 본문으로 POST /v1/jobs를 새 멱등 키와 함께 보내면 새 잡이 됩니다
업로드 소스는 잡 하나에만 쓰이고 잡이 끝나면 지워지므로, 업로드 잡을 다시 돌릴 때는 폴더를 다시 올려야 합니다
CLI build가 이 과정을 한 번에 합니다
3. 플랫폼 오류 (platform_error)
VM 준비 실패, 러너 장애, 서버 재시작으로 끝난 잡은 platform_error이고 금액은 0입니다
원장에 아무것도 기록하지 않습니다
- VM 준비가 한 번 실패하면 잡은 접수 순서를 유지한 채 대기열로 돌아가 다른 VM에서 한 번 더 시도합니다, 로그에
[xenoci] VM 준비 실패, 다른 VM으로 다시 시도합니다 (과금 없음)이 남습니다 - 두 번째도 실패하면
platform_error로 끝납니다 - 서버가 재시작되면 그때 준비 중이거나 실행 중이던 잡은
platform_error로 끝나고 로그에[xenoci] 서버 재시작으로 잡이 끝났습니다 (과금 없음)이 남습니다
platform_error는 같은 본문으로 바로 다시 보내면 됩니다
잡의 error.retryable이 true입니다
4. 실행 중 멈춘 경우
| 상태 | 뜻 | 다시 보내려면 |
|---|---|---|
timed_out | 제한 시간 초과 | timeout_minutes를 늘려 다시 제출 (최대 360) |
credit_exhausted | 잔액 소진 | 충전 뒤 다시 제출 실행했던 분은 과금됨 |
cancelled | 취소됨 | 필요하면 다시 제출 |
종료 코드로 구분하기
CLI build, wait와 GitHub Actions 단계는 잡 결과를 종료 코드로 돌려줍니다
| 종료 코드 | 뜻 |
|---|---|
| 0 | succeeded |
| 스크립트의 코드 (1 이상) | failed 그 스크립트의 종료 코드 그대로 |
| 3 | 잔액 부족이나 한도 초과로 시작하지 못했거나 credit_exhausted로 멈춤 |
| 124 | wait --timeout이 다 될 때까지 끝나지 않음 |
GitHub Actions에서는 종료 코드 3과 함께 ::error title=XenoCI 잔액 소진::…충전: <링크> 한 줄이 주석으로 남습니다
알림
잔액이 기준 아래로 내려가거나 잡이 credit_exhausted로 끝나면 조직 소유자와 관리자에게 메일이 갑니다
워크스페이스 월 한도와 티어 월 한도는 75%, 90%, 100%에서 한 번씩 알립니다
콘솔 알림 메뉴에서 종류별로 끄고 켤 수 있습니다