Claude Code의 외부 API 400 오류, Artifact 스키마부터 확인하기
Artifact input_schema 호환성 오류를 다른 HTTP 400과 구분하고 실제 실행 중인 Claude Code 버전과 수정 적용 여부를 확인하는 방법입니다.
Ofox 
업데이트 뒤 Claude Code가 매 턴 실패하고 오류에 Artifact 도구 입력 스키마의 잘못된 정규식이 언급된다면 키나 모델을 바꾸기 전에 클라이언트 버전을 확인하세요. 공식 저장소의 사용자 보고 #92969는 2.1.265와 2.1.266에서 Unicode 속성 이스케이프가 포함된 스키마 pattern을 엄격한 검증기가 거부하는 회귀 문제를 보고합니다.
특정한 과거 호환성 오류이며 모든 HTTP 400의 원인은 아닙니다. 모든 현재 클라이언트에 남아 있는 미해결 문제로 소개해서도 안 됩니다. 공식 Claude Code 변경 내역은 외부 엔드포인트 관련 수정을 2.1.268에 기록합니다.
수정 전에 오류가 일치하는지 확인하기
영향받은 클라이언트 업데이트부터 실패가 시작됐는지, 외부 Anthropic 호환 엔드포인트인지, 오류가 Artifact 스키마나 ‘not a regex’인 pattern을 가리키는지 확인합니다. 구체적인 문구는 검증기마다 다를 수 있습니다.
스키마 거부는 모델이 답하기 전에 발생합니다. 따라서 복잡한 코딩 요청을 인사말로 바꿔도 오류가 같을 수 있습니다. 모델 자체가 고장 났다는 뜻이 아니라 요청에 함께 들어간 도구 정의가 잘못됐을 수 있습니다.
| 오류 단서 | 조사할 항목 |
|---|---|
| Artifact input_schema와 잘못된 pattern | 영향받은 버전과 수정 버전 |
| tool_use 뒤 tool_result 누락 | 대화 및 도구 결과 순서 |
| 잘못된 thinking 서명 | thinking 블록 보존과 제공자 호환성 |
| 401 또는 403 | 인증과 권한을 별도로 확인 |
| 429 | 스키마 문법보다 사용 제한 확인 |
표는 조사 방향을 정하는 도구이지 자동 진단은 아닙니다. 민감정보를 제거한 전체 오류를 저장하고 필드 경로를 원래 보고와 비교하세요. 요청 한 건이 거부됐다고 관련 없는 보호 설정을 없애거나 모든 도구 스키마를 다시 작성하지 마세요.
실제 실행 중인 버전 확인하기
다음 명령의 결과부터 확인합니다.
claude --version터미널, IDE, 백그라운드 워커를 쓴다면 각각 확인하세요. 서로 다른 설치본일 수 있습니다. 평소 설치 방식으로 업데이트한 뒤 해당 클라이언트나 워커를 재시작하고 버전을 다시 확인합니다.
2.1.268은 수정을 포함한 과거 릴리스입니다. 지원 중인 최신 설치본을 그 버전으로 낮추라는 권고가 아닙니다. 조직에서 지원하는 현재 버전을 사용하세요. 영향받는 버전으로 고정한 환경이라면 그 고정도 진단에 포함하고 정상 업데이트 절차를 따릅니다.
요청을 구성하는 클라이언트에 업데이트가 적용돼야 합니다. 관련 없는 로컬 터미널만 업데이트해도 별도로 배포된 워커는 바뀌지 않습니다. 실패 요청과 성공한 재시험 요청을 각각 어떤 프로세스가 보냈는지 기록합니다.
긴 작업을 재시작하기 전에 요청 한 건으로 재시험하기
처음에는 제공자와 모델을 유지합니다. 부작용 없는 작업으로 원래 스키마 오류가 남는지 기록하세요. 업데이트 후 성공하면 그 구성에서 진단을 뒷받침하지만 제공자의 모든 기능을 보증하지는 않습니다.
그다음 관련 도구 워크플로를 시험합니다. 텍스트 답변만으로 같은 도구 호출 흐름을 검증할 수는 없습니다. 클라이언트 버전, 제공자 경로, 시각, 비식별 오류와 요청 ID를 보관하세요. 현재 버전에서도 거부된다면 같은 과거 오류라고 가정하지 말고 새 오류의 필드 경로를 비교합니다.
이 글은 상위 프로젝트의 이슈와 릴리스 근거를 바탕으로 합니다. Ofox 운영 환경에서 재현하거나 여러 게이트웨이의 성공률을 측정했다고 주장하지 않습니다.
‘Anthropic 호환’만으로 충분하지 않은 이유
인증, 메시지 구조, 스트리밍은 호환돼도 지원하는 JSON Schema 기능은 다를 수 있습니다. 보고된 실패는 내장 도구 정의의 pattern을 검증기가 처리하는 방식에 관한 것이며 모델의 코드 추론 능력과는 별개입니다.
생성된 정규식을 임의로 고치거나 운영 환경에서 검증을 끄지 마세요. 원치 않는 값을 허용하거나 다른 호환성 오류를 가릴 수 있습니다. 우선 클라이언트의 공식 수정을 적용하고 남는 문제는 비밀정보를 제거한 최소 예제로 제공자에게 전달합니다.
보고할 때는 거부된 구문을 보여 주는 최소 스키마 조각만 포함하세요. 비공개 프로젝트 프롬프트 전체는 필요하지 않습니다. 소스 코드, 환경변수, 전체 대화 이력을 넘기지 않고도 검증기를 조사할 정보를 제공할 수 있습니다.
다른 400 오류와 구분하기
tool_result 누락 가이드는 중단되거나 잘못 구성된 도구 교환을 다룹니다. thinking 서명 가이드는 다른 메시지 보존 문제를 다룹니다. 오류 근거가 일치하지 않으면 Artifact 설명으로 대체하지 마세요.
지원 요청에는 관찰한 실패부터 씁니다. 클라이언트 버전, 엔드포인트 유형, 거부된 필드, 정확한 오류가 필요합니다. ‘Claude Code가 안 된다’만으로는 수정된 클라이언트 문제와 현재 제공자 문제를 구분할 수 없습니다.
자주 묻는 질문
- Artifact pattern 회귀 문제는 어느 버전에서 수정됐나요?
- 공식 변경 내역은 2.1.268에 수정을 기록합니다. 그 과거 버전으로 낮추지 말고 지원되는 현재 클라이언트를 사용하세요.
- 이 오류가 나면 API 키를 교체해야 하나요?
- 스키마 검증 오류는 키가 잘못됐다는 증거가 아닙니다. 응답이 인증 문제를 가리키면 별도로 조사하되, 키 교체는 이 pattern 오류의 문서화된 해결책이 아닙니다.
- 외부 엔드포인트의 400은 모두 같은 원인인가요?
- 아닙니다. 스키마 필드, 클라이언트 버전, 오류 문구를 맞춰 확인하세요. 도구 결과 순서, 미지원 매개변수, thinking 서명은 각각 별도 점검이 필요합니다.
