오류
API 오류 코드와 처리 방법에 대한 가이드
HTTP 오류
저희 API는 예측 가능한 HTTP 오류 코드 형식을 따릅니다:
-
400 -
invalid_request_error
: 요청의 형식이나 내용에 문제가 있습니다. 아래에 나열되지 않은 다른 4XX 상태 코드에도 이 오류 유형을 사용할 수 있습니다. -
401 -
authentication_error
: API 키에 문제가 있습니다. -
403 -
permission_error
: API 키가 지정된 리소스를 사용할 권한이 없습니다. -
404 -
not_found_error
: 요청된 리소스를 찾을 수 없습니다. -
413 -
request_too_large
: 요청이 허용되는 최대 바이트 수를 초과합니다. -
429 -
rate_limit_error
: 계정이 속도 제한에 도달했습니다. -
500 -
api_error
: Anthropic 시스템 내부에서 예상치 못한 오류가 발생했습니다. -
529 -
overloaded_error
: Anthropic의 API가 일시적으로 과부하 상태입니다.529 오류는 Anthropic API가 모든 사용자에게 높은 트래픽을 경험할 때 발생할 수 있습니다. 드물게 조직의 사용량이 급격히 증가하는 경우 이러한 유형의 오류가 나타날 수 있습니다. 529 오류를 방지하려면 트래픽을 점진적으로 늘리고 일관된 사용 패턴을 유지하세요.
SSE를 통해 스트리밍 응답을 받을 때, 200 응답을 반환한 후에 오류가 발생할 수 있으며, 이 경우 오류 처리는 이러한 표준 메커니즘을 따르지 않습니다.
오류 형태
오류는 항상 JSON으로 반환되며, 항상 type
과 message
값을 포함하는 최상위 error
객체가 있습니다. 예를 들어:
저희 버전 관리 정책에 따라 이러한 객체 내의 값을 확장할 수 있으며, type
값이 시간이 지남에 따라 증가할 가능성이 있습니다.
요청 ID
모든 API 응답에는 고유한 request-id
헤더가 포함됩니다. 이 헤더에는 req_018EeWyXxfu5pfWkrYcMdjWG
와 같은 값이 포함됩니다. 특정 요청에 대해 지원팀에 문의할 때 이 ID를 포함해 주시면 문제를 신속하게 해결하는 데 도움이 됩니다.
저희 공식 SDK는 request-id
헤더의 값을 포함하는 최상위 응답 객체의 속성으로 이 값을 제공합니다:
긴 요청
특히 10분 이상 걸리는 장시간 실행 요청의 경우 스트리밍 Messages API 또는 Message Batches API 사용을 강력히 권장합니다.
저희 스트리밍 Messages API 또는 Message Batches API를 사용하지 않고 큰 max_tokens
값을 설정하는 것은 권장하지 않습니다:
- 일부 네트워크는 가변적인 시간 후에 유휴 연결을 끊을 수 있으며, 이로 인해 Anthropic으로부터 응답을 받지 못하고 요청이 실패하거나 시간 초과될 수 있습니다.
- 네트워크의 신뢰성은 다양합니다. 저희 Message Batches API는 중단되지 않는 네트워크 연결을 요구하는 대신 결과를 폴링할 수 있게 하여 네트워크 문제의 위험을 관리하는 데 도움이 될 수 있습니다.
직접 API 통합을 구축하는 경우 TCP 소켓 keep-alive 설정이 일부 네트워크에서 유휴 연결 시간 초과의 영향을 줄일 수 있다는 점을 알아야 합니다.
저희 SDK는 비스트리밍 Messages API 요청이 10분 시간 초과를 초과할 것으로 예상되지 않는지 검증하고 TCP keep-alive를 위한 소켓 옵션도 설정합니다.