feat(api): give the full build queue, auth failures and the overload 503 a stable code

[Eomdahyeon]

Closes #1000

#1022(#996) 위에 쌓은 PR 이다. base 를 그 브랜치로 잡아 이 PR 의 diff 만 보이게 했다. #1022 가 머지되면 base 를 main 으로 바꾼다.

문제

일부 에러 본문에 code 가 없어서 클라이언트가 문장으로 분기해야 한다. 특히 POST /builds 의 큐 초과 429 는 auth_throttled 429 와 문장으로만 구분됐다.

변경 내용 — 이슈의 네 가지

경우	상태	code
async build 큐 초과	429	build_queue_full
인증 실패	401	unauthorized, 토큰의 exp 가 지났으면 token_expired
JWKS 를 가져오지 못함	503	auth_unavailable
과부하 (요청을 읽기 전 소켓 응답)	503	server_overloaded
재시작으로 중단된 run	—	credentials_required — #1022 에서

• 본문의 error 문장은 그대로 둔다. code 만 추가된다.
• 401 본문은 이슈가 "확인하지 않은 것"으로 남긴 부분이다. 확인: {"error": <AuthError.reason>} 이었고 code 가 없었다. AuthError.code 프로퍼티가 상태와 사유에서 코드를 정한다.
• token_expired 를 따로 둔 이유: 클라이언트가 할 일이 다르다(토큰을 새로 받아 재시도). 나머지 401 은 unauthorized 하나다 — 어떤 검증이 실패했는지까지 코드로 나누지 않았다.
• 계약 1.78.0 → 1.79.0 (additive): Error.code 설명에 코드 목록, Unauthorized 응답의 예시와 설명, submitBuild 429 예시. Error 스키마에는 이미 선택적 code 가 있어 스키마 구조는 바뀌지 않는다.

검증

• tests/unit/test_stable_error_codes.py(큐 초과 본문, 과부하 본문), test_oidc_auth.py::TestStableAuthCodes(거부·JWKS 불가·만료 토큰이 실제 응답 본문에 싣는 코드).
• 인증·서비스·계약 fixture·job 관련 테스트 파일: 721 passed. 전체 스위트는 돌리지 않았다 — CI 가 확인한다.
• check_contract_compat.py: origin/main 대비 1.77.0 -> 1.79.0 호환. ruff, mypy 통과.

겹치는 것

#1009 가 계약의 같은 영역(공용 응답, 버전 줄)을 고친다. 나중에 머지되는 쪽에서 버전 줄을 맞춰야 한다.

🤖 Generated with Claude Code

[yeongseon]

리뷰 (코멘트 — #1022 위에 쌓인 PR 이라 승인은 base 가 main 으로 바뀌고 체크가 녹색인 뒤에).

diff 를 읽었습니다. error 문장을 그대로 두고 code 만 더한 것, token_expired 만 따로 둔 이유(클라이언트가 할 일이 다르다) 모두 타당합니다.

확인해 주면 좋은 것 두 가지 (막는 것은 아님):

• Unauthorized 응답 예시의 error 가 unauthorized → invalid api key 로 바뀌었습니다. 이 예시는 키가 누락된 경우도 대표하는데, 그때 서버가 실제로 내는 문장이 같은지 본문에 근거가 없습니다. fixture 가 예시에서 생성되므로 실제 응답과 다르면 fixture 가 사실과 어긋납니다.
• token_expired 판정이 reason.endswith("ExpiredSignatureError") 문자열에 묶여 있습니다. 테스트가 고정하고 있어 지금은 괜찮지만, reason 형식을 바꾸면 조용히 unauthorized 로 내려갑니다 — AuthError 를 만드는 자리에서 종류를 넘기는 쪽이 더 단단합니다.

로컬에서 테스트를 돌리지는 않았습니다.

[Eomdahyeon]

머지 순서 주의. 이 PR 이 추가하는 에러 예시와 code 는 Studio 의 드리프트 검사(ERROR_READERS)가 아직 모른다. Builder main 에 들어가면 Studio 의 모든 PR 에서 Builder contract drift 가 실패한다 — 이 스택의 계약으로 Studio 드리프트 테스트를 돌려 확인했다(7개 실패). kpubdata-lab/kpubdata-studio#743 이 그 항목들을 버전 조건과 함께 추가하므로, #743 을 먼저 머지한 뒤 이 PR 을 넣어야 한다. #743 은 지금 Builder main(1.77.0)에서도 통과한다.

[Eomdahyeon]

리뷰 두 가지 반영했습니다.

• Unauthorized 예시의 문장: 키가 누락된 경우와 틀린 경우 모두 _verify_api_key 의 같은 마지막 줄(AuthError(reason="invalid api key"))로 떨어집니다 — api_key is None 이면 비교를 건너뛰고 그 줄로 갑니다. 그래서 예시 하나가 두 경우를 대표하는 것이 사실과 맞습니다. 근거를 본문이 아니라 테스트로 남겼습니다: test_a_missing_key_and_a_wrong_key_get_the_contract_example 가 None 과 "wrong-key" 양쪽에서 ("invalid api key", "unauthorized") 를 고정합니다. (서버에 키가 설정되지 않은 경우는 api key not configured 로 문장이 다르지만 코드는 같은 unauthorized 이고, 예시가 대표한다고 적은 경우는 아닙니다.)
• token_expired 판정: AuthError 에 expired: bool 필드를 두고 jwt.decode 의 except 에서 isinstance(exc, jwt.ExpiredSignatureError) 로 넘깁니다. code 는 더 이상 reason 을 읽지 않습니다. test_the_code_does_not_read_the_sentence 가 문장을 바꿔도 코드가 유지되고, 문장이 같은 꼴로 끝나도 플래그 없이는 unauthorized 임을 확인합니다.

CI 실패는 base 인 #1022 의 테스트 fixture 때문이었고(해제한 워커 스레드를 기다리지 않아 다음 테스트의 tracemalloc 측정에 섞임) 그쪽에서 고쳐 이 브랜치에 합쳤습니다.

로컬 실행: pytest tests/unit/test_oidc_auth.py tests/unit/test_stable_error_codes.py tests/unit/test_response_fixtures.py tests/unit/test_interrupted_run_status.py tests/unit/test_json_array_reader.py → 395 passed, ruff check / ruff format --check / mypy src 통과. 전체 스위트는 CI 에 맡겼습니다.