​
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으로 반환되며, 최상위 error 객체에는 항상 type과 message 값이 포함됩니다. 예를 들면:

JSON
{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "The requested resource could not be found."
  }
}

당사의 버전 관리 정책에 따라, 이러한 객체 내의 값을 확장할 수 있으며, type 값은 시간이 지남에 따라 증가할 수 있습니다.

​
요청 ID

모든 API 응답에는 고유한 request-id 헤더가 포함됩니다. 이 헤더에는 req_018EeWyXxfu5pfWkrYcMdjWG와 같은 값이 포함됩니다. 특정 요청에 대해 지원팀에 문의할 때는 이 ID를 포함하여 문제를 신속하게 해결할 수 있도록 도와주세요.

공식 SDK는 이 값을 최상위 응답 객체의 속성으로 제공하며, request-id 헤더의 값을 포함합니다:

import anthropic

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-opus-4-20250514",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Hello, Claude"}
    ]
)
print(f"Request ID: {message._request_id}")

​
긴 요청

특히 10분 이상 실행되는 요청의 경우 스트리밍 메시지 API 또는 메시지 배치 API를 사용하는 것을 적극 권장합니다.

스트리밍 메시지 API 또는 메시지 배치 API를 사용하지 않고 큰 max_tokens 값을 설정하는 것은 권장하지 않습니다:

  • 일부 네트워크는 일정 시간이 지나면 유휴 연결을 끊을 수 있으며, 이로 인해 Anthropic으로부터 응답을 받지 못한 채 요청이 실패하거나 타임아웃될 수 있습니다.
  • 네트워크의 신뢰성은 다양합니다; 메시지 배치 API는 중단 없는 네트워크 연결이 필요한 대신 결과를 폴링할 수 있게 함으로써 네트워크 문제의 위험을 관리하는 데 도움이 됩니다.

직접 API 통합을 구축하는 경우, TCP 소켓 keep-alive를 설정하면 일부 네트워크에서 유휴 연결 타임아웃의 영향을 줄일 수 있다는 점을 알아두세요.

당사의 SDK는 스트리밍되지 않는 메시지 API 요청이 10분 타임아웃을 초과하지 않도록 검증하고 TCP keep-alive를 위한 소켓 옵션도 설정합니다.