본문으로 건너뛰기
원포트 AI

Anthropic SDK

base_url 만 바꾸면 돼요.

AI 에게 넘기기ChatGPT 에서 열기 (새 창)Claude 에서 열기 (새 창)원문 열기
python
import os
import anthropic

client = anthropic.Anthropic(
    api_key=os.environ["ONEPORT_API_KEY"],   # 원포트 키(sk-so-...)
    base_url="https://oneport.kr",
)

message = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "안녕하세요"}],
)
print(next(b.text for b in message.content if b.type == "text"))
TypeScript · JavaScript — 옵션 이름만 baseURL, 여기도 /v1 은 안 붙여요
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  apiKey: process.env.ONEPORT_API_KEY,
  baseURL: "https://oneport.kr",
});

const message = await client.messages.create({
  model: "claude-sonnet-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "안녕하세요" }],
});

부를 수 있는 Claude 모델 id 는 GET https://oneport.kr/v1/models(키 없이 열려요)에서 보세요. 키를 붙여 부르면 그 키로 부를 수 있는 모델만 와요. 목록 id 를 글자 그대로 쓰세요 — 다만 기존 코드의 claude-sonnet-4-5-20250929 처럼 끝에 날짜(-YYYYMMDD)가 붙은 이름은 그대로 보내셔도 돼요. 날짜를 떼고 목록 id(claude-sonnet-4-5)로 불러요. 목록과 견주는 코드라면 날짜를 떼고 견주세요. 줄의 retirement 는 null 이거나 {"date": "YYYY-MM-DD", "successors": [바꿔 넣을 id]} 예요. Claude 줄의 endpoint 칸은 POST /v1/chat/completions 로 나오지만, 이 SDK 로 /v1/messages 에 그대로 불러요.

되는 것 · 안 되는 것#

  • 돼요 — 스트리밍 · 직접 만든 도구 · thinking · cache_control · 그림 · PDF(base64 블록) · 토큰 미리 세기 · anthropic-beta 머리글(그대로 넘겨요).
  • 안 돼요 — 묶음 처리(/v1/messages/batches)와 파일 올리기(/v1/files)는 404 not_found_error 예요. 묶음에 넣던 요청은 한 건씩 /v1/messages 로 보내고(동시에 보내셔도 돼요 — 저희가 정한 동시 건수 제한은 없어요. 다만 잔액만으로는 이 요청 몫이 들어가는데 다른 호출이 잡아 둔 몫을 빼면 모자랄 때 그 요청만 402 insufficient_credit · error.reason held_by_others(Retry-After: 5)로 와요 — 그만큼 기다렸다 그대로 다시 보내요. 잔액 자체가 이 요청 몫보다 작으면 error.reason 이 hold_exceeds_balance 라 기다려도 안 풀려요 — 충전하거나 max_tokens 를 줄여요 · Python 은 e.body["error"].get("reason"), Node 는 err.error.error.reason), 파일은 메시지 안에 base64 로 넣어요. 오류 문장도 같은 방법을 알려 줘요. 자세한 건 「Anthropic·OpenAI 콘솔에서 옮겨 오기」 장에 있어요.
  • 묶음 문이 없어서 묶음 할인도 없어요 — 한 건씩 목록 단가 그대로예요. 답 본문은 저희가 보관하지 않아서(아래 조회 주소로도 못 받아요) 받는 즉시 저장해 두세요. 키에 월 한도를 걸었으면 같은 키로 동시에 보낸 호출 몫 때문에 429 key_limit_exceeded · held_by_others 도 와요(아래 「안 될 때」 429 줄).

프롬프트 캐시와 값#

cache_control 은 그대로 넘어가요. 응답 usage 의 cache_creation_input_tokens · cache_read_input_tokens · cache_creation.ephemeral_1h_input_tokens 도 Anthropic 그대로 와요. input_tokens 는 캐시 몫을 뺀 나머지예요. 단가는 GET /v1/models 의 pricing.rates 에서 dimension 이 cache_read · cache_write 인 줄을 보세요(100만 토큰당 크레딧). cache_write 는 5분 캐시 값이에요 — 목록의 cache_write 줄 값이 정본이에요(10월 기준 Claude 줄은 모두 input_text 의 1.25배). 스페이스 전송 정책을 켠 키도 요청 맨 위 cache_control(자동 캐시)을 그대로 받아요 — system · messages 블록 안 cache_control 과 같아요. ttl "1h" 쓰기는 줄이 따로 없어서 input_text 의 2배로 세요. 캐시 읽기 배수는 모델마다 달라요(claude-sonnet-5 는 입력의 10분의 1 · claude-sonnet-5-5 · claude-opus-5-5 는 20분의 1 · 10월 기준 · 정본은 목록) — 0.1배로 박아 두지 마세요. claude-sonnet-5-5 는 입력 · 출력 단가가 claude-sonnet-5 와 같아서, 같은 지시문을 여러 번 읽는 묶음 일엔 더 싸요. cache_control 을 실은 요청은 같은 지갑 · 같은 모델이면 키가 달라도 같은 길로 보내서 캐시가 이어져요. 그 길이 잠시 막혀 다른 길로 돌면 그 호출은 캐시를 새로 써요(cache_creation_input_tokens 가 다시 커져요). 긴 입력에 값이 오르는 모델(pricing.tier 가 있는 모델 · 10월 기준 Claude 는 claude-haiku-5-5)은 입력 토큰(input_tokens + cache_read_input_tokens + cache_creation_input_tokens)이 above_input_tokens 이상이면 그 요청 전체를 tier 단가로 세요. ttl "1h" 쓰기도 그 구간의 입력 단가 × 2 예요.

쓴 크레딧 · 요청 ID 남기기#

이 호출에 쓴 크레딧은 응답 usage.cost_credits 예요(웹 검색 요금까지). 정산이 2초 안에 안 끝나면 그 칸 없이 와요 — 그땐 usage 토큰 × GET /v1/models 의 pricing.rates 단가 ÷ 1,000,000 으로 셈해요(위 「프롬프트 캐시와 값」). Anthropic SDK 로 읽는 법이에요(SDK 동작). Python 은 getattr(message.usage, "cost_credits", None)(모르는 칸도 받아 둬요) · 요청 ID 는 message._request_id 예요. Node 는 (message.usage as any).cost_credits(TS 타입엔 없는 칸이라 형 변환해 읽어요) · 요청 ID 는 message._request_id 예요. 스트림이면 마지막 message_delta 이벤트의 event.usage 에서 cost_credits 를 읽어요(흐름 중간 이벤트엔 없어요) — 끝난 메시지를 모아 주는 get_final_message()(Node finalMessage())의 usage 엔 이 칸이 안 옮겨져요. 스트림의 요청 ID 는 Python 이 stream.response.headers["request-id"](messages.stream() 이면 stream.request_id), Node 가 messages.stream() 의 stream.request_id 나 messages.create({ …, stream: true }).withResponse() 의 response.headers.get("request-id") 예요. 스트림 도중에 오는 error 이벤트엔 요청 ID 가 없어서, 시작할 때 받은 머리글에서 읽어 두세요 — Python 은 with client.messages.stream(...) as s: 안에서 s.response.headers.get("request-id") · s.response.headers.get("x-gateway-status-url"), Node 는 const s = client.messages.stream(params); const { response } = await s.withResponse(); 뒤 response.headers.get("request-id") · response.headers.get("x-gateway-status-url") 예요(SDK 동작). 스트림이 도중에 끊기면 끝 usage(message_delta)가 안 와서 cost_credits 도 못 받아요. Idempotency-Key 를 실었으면 스트림 200 응답 머리글에도 x-gateway-status-url 이 오니, 끊긴 뒤 몇 초 지나 같은 API 키로 GET 해서 settlement.cost_credits 로 그 호출에 쓴 몫을 보세요(정산 전이면 null 이에요).

그림 · PDF 넣기#

Anthropic 문서대로 content 에 { type: "image", source: { type: "base64", media_type: "image/png", data } } 를 넣으세요(PDF 는 type: "document"). 몸통을 그대로 넘겨요. 요청 한 번은 4.5MB 까지이고, base64 는 원본보다 3분의 4배(약 1.33배)쯤 커지니 원본 3MB 를 넘는 그림은 줄여서 보내 주세요. 넘으면 저희 앞단에서 413 으로 끊겨요 — 이 오류는 JSON 이 아니라 영어 글자(FUNCTION_PAYLOAD_TOO_LARGE)라서 상태 코드 413 으로 가르세요. 이 413 엔 request-id 머리글도 없어요(저희 코드에 닿기 전이라). 스페이스 전송 정책을 켠 키는 그림 · PDF · 도구(tools)를 보낼 수 없어요(403 space_content_policy · code unsupported_capability).

부르기 전에 잡아 두는 몫에서 그림은 한 장에 4,800 토큰을 넘지 않게 잡지만, PDF 는 쪽 수가 아니라 base64 바이트 ÷ 3 으로 어림해서 실제보다 훨씬 크게 잡힐 수 있어요(Claude 는 목록 context_window 와 100만 토큰 가운데 큰 값의 1.05배까지만 입력 몫을 잡고, 그때는 그 구간의 가장 비싼 입력 단가로 잡아요 — 웹 검색 같은 서버 도구를 실으면 자르지 않아요 · 원본 2MB PDF 면 claude-sonnet-5 로 약 1,600 크레딧 · cache_control 을 붙이면 캐시 쓰기 단가라 약 2,000 크레딧 · 10월 기준 · 실제 사용은 Anthropic 이 센 토큰만큼). 잔액이나 키 한도가 그보다 작으면 max_tokens 를 줄여도 402 · 429 가 와요 — PDF 를 줄이거나 쪽을 나눠 보내 주세요. 대화 기록에 PDF 가 남아 있으면 턴마다 다시 잡아요. PDF 를 주소(source.type "url")로 붙이면 크기와 상관없이 위 창 상한만큼 잡아요 — 작은 PDF 는 base64 로 넣는 게 덜 잡혀요(「남은 한도」 장 「최대 몫」).

토큰 미리 세기#

보낼 몸통을 client.messages.countTokens({ model, messages, system, tools }) 로 보내면 입력 토큰 수(input_tokens)만 와요 — POST https://oneport.kr/v1/messages/count_tokens 예요. max_tokens · stream 은 빼 주세요. 요금이 안 붙고 크레딧도 안 잡아요. Claude 모델만 받고(다른 모델은 400 · 목록에 없는 id 는 404 model_not_found), anthropic-beta 머리글도 그대로 넘겨요. 받는 칸 · 오류는 「글 (Anthropic 형식)」 장의 「토큰 미리 세기」 절에 있어요. Python 은 client.messages.count_tokens(model=..., system=..., messages=...) 이고 반환값의 input_tokens 를 읽어요(SDK 동작). cache_control 이 붙은 블록도 그대로 넘겨요. 이 문은 Idempotency-Key 를 읽지 않고 사용 기록도 안 남겨서, 일시 실패는 같은 몸통으로 그대로 다시 불러요.

typescript
const { input_tokens } = await client.messages.countTokens({
  model: "claude-sonnet-5",
  messages: [{ role: "user", content: "안녕하세요" }],
});

생각(thinking) 켜기#

지금 모델(claude-sonnet-5 · claude-opus-5 · claude-opus-5-5 등)은 thinking 을 {"type": "adaptive"} 로 켜요. budget_tokens 를 넣으면 Anthropic 이 400 으로 돌려보내고, 그 문장이 400 upstream_error 로 그대로 와요. 생각의 깊이는 output_config.effort(low · medium · high · xhigh · max)로 정해요. claude-haiku-4-5 · claude-sonnet-4-5 는 output_config.effort 를 안 받아요(supports_effort 가 false) — 이 둘에 부를 땐 effort 칸을 빼 주세요. 받는 모델인지는 GET /v1/models 의 supports_effort 로 보세요(claude-sonnet-4-6 · claude-opus-4-6 은 xhigh 를 안 받아요). 생각한 토큰은 usage.output_tokens 안에 들어 출력 단가로 사용해요 — 따로 더하지 마세요. SDK 판이 output_config 칸을 모르면 extra_body 로 실어요(SDK 동작).

생각 켜고 깊이 정하기
r = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    output_config={"effort": "high"},
    messages=[{"role": "user", "content": "분수 나눗셈을 그림으로 설명하는 수업 흐름을 짜 줘"}],
)
answer = next(b.text for b in r.content if b.type == "text")

스트리밍#

받는 대로 흘려받기
with client.messages.stream(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "분수 단원 수업 계획을 써줘"}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

흐름이 열리기 전의 시계는 둘이에요 — 모델 회사로 보낸 뒤 첫 응답 머리말을 120초 안에 못 받으면 422 upstream_execution_unconfirmed(보냈으니 실행됐을 수 있어요 · 자동으로 다시 보내지 않아요)이고, 504 error.reason "timeout" 은 모델 회사가 실행하기 전에 저희 처리 기한(4분)이 끝난 거라 요금 없이 한 번 다시 보내도 돼요(아래 「오류 가르기」). 조각 사이가 120초 비거나 시작부터 약 12분 50초가 되면 저희가 마지막에 event: error(type api_error · 문장 「처리 시간을 넘어 답이 도중에 끊겼어요 …」)를 보내고 흐름을 닫아요 — SDK 는 이걸 오류로 던져요. 답 도중 Anthropic 이 보낸 event: error 는 그 type 그대로(overloaded_error · api_error 등) 넘겨요. 저희가 끊을 때(조각 사이 120초 · 약 12분 50초 · 모델 회사 연결 끊김)도 type 은 api_error 예요 — Anthropic 이 보낸 api_error 와 이름이 같아 type 만으로는 못 갈라요. 어느 쪽이든 잘린 답이라, 상태 코드로 온 503 api_error(보내기 전 일시 장애 · 그대로 다시)와 달리 처음부터 다시 보내지 말고 받은 글을 assistant 메시지로, 이어 써 달라는 user 메시지를 그 뒤에 붙여 새 Idempotency-Key 로 이어 받아요 — assistant 로 끝내면 지금 목록의 Claude 대부분이 400 이에요. 이 오류는 Node SDK 면 err.status 가 비어 있고, Python SDK 면 e.status_code 가 처음 받은 200 이에요(SDK 동작 · 갈래는 아래 「오류 가르기」). 손님 서버와 저희 사이 연결이 먼저 끊기면 오류 프레임 없이 닫힐 수 있어요 — Node SDK 는 message_stop 없이 닫힌 흐름이면 finalMessage() 가 Anthropic.AnthropicError(APIError 가 아니에요)를 던지고, Python SDK 는 stop_reason 을 돌려주기 전에 예외를 낼 수 있어요(SDK 동작) — catch 에서 잘린 답으로 받으세요(Python 은 with client.messages.stream(...) 블록을 try 로 감싸요). stop_reason 이 null 인 채로 끝나는 클라이언트도 잘린 답이에요. 끊기기 전까지 쓴 토큰은 사용했어요. 시간 셈은 「글 (Anthropic 형식)」 장의 스트리밍 절에 있어요.

SDK 판과 anthropic-version#

SDK 는 큰 판마다 정해진 anthropic-version 을 실어요 — Python 2.x · TypeScript 1.x · Go v2 · Ruby 2.x · PHP 1.x · Java 3.x · C# 13.x · ant CLI 2.x 는 2026-10-21, 그 이전 판은 2023-06-01 이에요(벤더 동작) — npm 의 @anthropic-ai/sdk 0.x(0.115 등)도 이전 판이에요. 깔린 판은 npm ls @anthropic-ai/sdk · pip show anthropic 으로 보세요. 저희는 받은 값을 그대로 넘겨요. 2026-10-21 판에선 temperature · top_p · top_k 가 없어져서(새 판 SDK 엔 칸도 없어요) 값을 읽는 모델에 실으면 보내기 전에 400 이에요. assistant 메시지에 바로 넣은 document 블록과 user 메시지 text 의 비지 않은 citations 도 Anthropic 이 400 upstream_error 로 돌려보내요 — document 는 user 메시지로 옮기고 citations 는 빼 주세요. 옛 동작이 필요하면 default_headers(TypeScript 는 defaultHeaders)로 2023-06-01 을 주세요. 판별 차이 전체는 「글 (Anthropic 형식)」 장의 「anthropic-version 판」 절이에요.

옛 판(2023-06-01)으로 묶어 두기 — 새 판 SDK 에선 temperature 를 extra_body 로 실어요(SDK 동작)
import os
import anthropic

client = anthropic.Anthropic(
    api_key=os.environ["ONEPORT_API_KEY"],
    base_url="https://oneport.kr",
    default_headers={"anthropic-version": "2023-06-01"},
)

r = client.messages.create(
    model="claude-haiku-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "안녕하세요"}],
    extra_body={"temperature": 0.2},
)

도구 루프#

직접 만든 도구는 type 을 안 적거나 "custom" 으로 적고, name · description · input_schema 를 적으세요. 응답의 stop_reason 이 "tool_use" 면 그 content 를 assistant 메시지로 그대로 쌓고, 도구를 돌린 결과를 tool_result(tool_use_id 를 맞춰서)로 담아 user 메시지로 다시 보내요. 한 응답에 tool_use 가 여러 개 오면 결과를 한 user 메시지에 다 담아요. 스페이스 전송 정책을 켠 키로 tools 를 실으면 첫 호출부터 403 space_content_policy 예요 — 도구 루프는 정책이 꺼진 키로 돌려 주세요.

도구 하나로 끝까지 (TypeScript)
const tools: Anthropic.Tool[] = [{ name: "get_weather", description: "도시의 지금 날씨", input_schema: { type: "object", properties: { city: { type: "string" } }, required: ["city"] } }];
const messages: Anthropic.MessageParam[] = [{ role: "user", content: "서울 날씨 알려줘" }];
for (;;) {
  const res = await client.messages.create({ model: "claude-sonnet-5", max_tokens: 1024, tools, messages });
  messages.push({ role: "assistant", content: res.content });
  if (res.stop_reason !== "tool_use") break;
  const results = res.content
    .filter((b): b is Anthropic.ToolUseBlock => b.type === "tool_use")
    .map((b) => ({ type: "tool_result" as const, tool_use_id: b.id, content: JSON.stringify({ city: (b.input as { city: string }).city, temp: 18 }) }));
  messages.push({ role: "user", content: results });
}

웹페이지에서 직접 부르기#

HTML 파일이나 웹페이지의 자바스크립트로 바로 부를 땐 요청에 anthropic-dangerous-direct-browser-access: true 머리글을 붙이세요. Anthropic 과 같은 규칙이에요. 이 머리글이 없으면 브라우저의 사전 요청(OPTIONS)이 허용 답을 못 받아 CORS 오류로 막혀요 — 요청이 저희까지 오지도 않아요. 값은 true 그대로예요 — 1 같은 다른 값이면 요청은 실행돼 요금이 붙는데 응답을 브라우저가 못 읽어요. x-api-key 대신 Authorization: Bearer 를 실어도 되고, anthropic-version 은 빼도 돼요(없으면 2023-06-01 로 채워 보내요). Anthropic SDK 는 dangerouslyAllowBrowser: true 로 두면 알아서 붙여요. fetch 로 부를 땐 SDK 와 달리 https://oneport.kr/v1/messages 처럼 /v1 까지 다 적어요. 이 머리글을 실으면 어느 사이트(Origin)에서 불러도 열려요. 모델 목록(/v1/models) · 남은 몫(/v1/key · /v1/credits)도 같은 머리글을 실어야 브라우저에서 읽혀요.

js
const res = await fetch("https://oneport.kr/v1/messages", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    "x-api-key": KEY,
    "anthropic-version": "2023-06-01",
    "anthropic-dangerous-direct-browser-access": "true",
  },
  body: JSON.stringify({ model: "claude-haiku-5-5", max_tokens: 1024, messages: [{ role: "user", content: "안녕하세요" }] }),
});

오류 가르기 (TypeScript · Python)#

Anthropic SDK 는 Anthropic.APIError 의 err.status 와 err.error.error.type 으로 갈라요. 402 는 err.error.error.reason 으로 갈래가 와요 — "held_by_others"(잠시 뒤 그대로) · "hold_exceeds_balance"(max_tokens 를 줄이거나 충전) · "below_minimum_balance"(충전). /v1/messages 의 402 엔 늘 이 reason 이 와서 문장으로 가르지 않아요(hold_exceeds_balance 안의 할 일만 문장이 더 알려 줘요 — 아래 예시). 429 group_limit_exceeded 도 같은 자리예요 — "group_budget"(max_tokens 를 줄여 볼 수 있어요) · "group_closed" · "group_not_started" · "group_ended"(멈추고 스페이스 관리자에게). Python 은 e.body["error"].get("reason") 이에요. 연결 오류(Anthropic.APIConnectionError)는 저희 쪽 호출이 이미 끝났을 수 있어요. APIConnectionError 도 APIError 라서 err.status 가 비어 있어요 — instanceof APIConnectionError 를 먼저 보고, signal 로 직접 끊은 APIUserAbortError 를 뺀 뒤 status 가 빈 APIError 는 스트림 도중 끊긴 잘린 답(위 「스트리밍」)으로 받으세요(SDK 동작). API 키 한도 429(key_limit_exceeded — error.reason 이 held_by_others 면 빼고)와 강좌 몫 429(group_limit_exceeded)에는 x-should-retry: false 가 붙고, Idempotency-Key 를 실으면 모델 회사가 거절한 4xx upstream_error 에도 붙어요 — 이 셋은 상태 조회할 일이 아니라 고쳐 보내거나 멈출 일이라 x-should-retry 보다 먼저 갈라요(held_by_others 는 402 처럼 상태 조회 갈래 뒤에서 가르세요). 고친 요청엔 새 Idempotency-Key 를 써요. 504 error.reason "timeout" 도 그 머리글이 붙지만 잠시 뒤 한 번은 같은 Idempotency-Key · 같은 본문으로 다시 보내도 돼요. 접수 기록을 잠깐 못 읽은 503 request_state_unavailable · request_store_unavailable 도 잠시 뒤 같은 Idempotency-Key · 같은 본문으로 한 번 다시 보내요(Retry-After 가 오면 그만큼). 접수 뒤에 나서 조회 주소 · x-should-retry: false 와 같이 와도 그래요 — 모델 회사로 보내기 전에 멈춘 접수면 새로 실행되고, 아니면 409 와 조회 주소가 와요. 상태 조회는 그 밖에 x-should-retry: false 와 조회 주소(x-gateway-status-url)가 같이 온 실패만 해요 — 조회 주소 자체는 Idempotency-Key 를 실어 접수된 뒤의 응답엔 늘 와요(접수 전에 막힌 401 · 400 · 413 · 409 idempotency_conflict · 503 엔 없어요). x-should-retry: false 없이 온 5xx upstream_error(529 포함 — type 이 upstream_error 라 상태 코드로 가르세요)는 실행 전에 막힌 거라, 기다렸다 그대로 다시 보내도 돼요(Idempotency-Key 를 실었으면 같은 Idempotency-Key · 같은 본문). Python 은 아래 두 번째 코드가 같은 순서예요(SDK 동작). 갈래 전체는 「에러」 장이에요.

typescript
try {
  // client.messages.create(...) · 스트림이면 await stream.finalMessage()
} catch (err) {
  if (err instanceof Anthropic.APIConnectionError) { /* 실행 불명 — Idempotency-Key 없이 불렀으면 자동 재전송 금지 · 실었으면 같은 Idempotency-Key · 같은 본문으로 한 번 */ }
  else if (err instanceof Anthropic.APIUserAbortError) { /* signal 로 직접 끊은 것 — 다시 보내지 않아요 */ }
  else if (err instanceof Anthropic.APIError && err.status === undefined) { /* 스트림 도중 온 event: error — 잘린 답. 처음부터 다시 보내지 말고 받은 글로 이어 받기(「에러」 장 「잘린 답 이어 받기」 · 도구 호출 · 생각 블록이 반쯤 왔으면 그 턴만 새 Idempotency-Key 로 다시) */ }
  else if (err instanceof Anthropic.APIError) {
    const body = (err.error as { error?: { type?: string; message?: string; reason?: string } } | undefined)?.error;
    const type = body?.type;
    const reason = body?.reason;
    const h = err.headers as any;
    const header = (name: string) => (typeof h?.get === "function" ? h.get(name) : h?.[name]) ?? null;
    const noRetry = header("x-should-retry") === "false";
    const statusUrl = header("x-gateway-status-url");   // Idempotency-Key 를 실어 접수된 뒤의 응답엔 늘 와요 — 조회는 noRetry 와 같이 왔을 때만
    if (type === "group_limit_exceeded") { /* reason 이 group_budget 이면 GET /v1/key 의 group 남은 몫이 0 보다 클 때 max_tokens 를 줄여 새 Idempotency-Key 로 다시 · group_tail 이면 출력 단가가 낮은 모델로 바꿔 새 Idempotency-Key 로 · group_closed · group_not_started · group_ended 면 멈추고 스페이스 관리자에게 */ }
    else if (type === "key_limit_exceeded" && reason !== "held_by_others") { /* key_month_limit 면 max_tokens 를 줄여 새 Idempotency-Key 로 · key_day_limit 면 한국 시간 0시까지 멈춰요 */ }
    else if (err.status === 504 && reason === "timeout") { /* 잠시 뒤 한 번만 같은 Idempotency-Key · 같은 본문으로 */ }
    else if (type === "upstream_error" && (err.status ?? 0) < 500) { /* 모델 회사가 거절 — 문장대로 고쳐서 새 Idempotency-Key 로 */ }
    else if (err.status === 503 && (type === "request_state_unavailable" || type === "request_store_unavailable")) { /* Retry-After 가 있으면 그만큼(조회 주소 없이 오면 2초), 없으면 직접 정한 간격만큼 기다렸다 같은 Idempotency-Key · 같은 본문으로 한 번 */ }
    else if (type === "upstream_execution_unconfirmed" || type === "request_already_exists" || (noRetry && statusUrl)) { /* 자동 재전송 금지 · statusUrl 을 GET 조회 */ }
    else if (type === "key_limit_exceeded") { /* held_by_others — 같은 키의 앞 호출 몫 · Retry-After(5초) 뒤 같은 Idempotency-Key · 같은 본문으로 그대로 */ }
    else if (type === "insufficient_credit" && reason === "held_by_others") { /* 잠시 뒤 그대로 다시 */ }
    else if (type === "insufficient_credit") {
      const msg = body?.message ?? "";   // 갈래는 reason — 문장은 hold_exceeds_balance 안의 할 일만 더 알려 줘요
      if (reason === "hold_exceeds_balance") { /* max_tokens 줄이기 — msg.includes("미리 잡는 몫 대부분이 입력") 이면 첨부 줄이기 · msg.includes("stream: true 로 보내거나") 면 stream: true · 아니면 충전 */ }
      else { /* below_minimum_balance — 충전 */ }
    }
    else if ((err.status === 429 && type === "rate_limit_error") || (type === "upstream_error" && (err.status ?? 0) >= 500 && !noRetry) || (err.status === 503 && type === "api_error")) { /* 529 도 여기 — Retry-After 가 있으면 그만큼, 없으면 직접 정한 간격만큼 기다렸다 다시 */ }
    else if (noRetry) { /* 다시 보내지 말고 문장대로 고치기(401 · 409 idempotency_conflict 등) */ }
    else if ((err.status ?? 0) >= 500) { /* 알려지지 않은 5xx — 자동 재전송하지 않고 확인 */ }
    else { /* 문장대로 고치기 */ }
  }
  else if (err instanceof Anthropic.AnthropicError) { /* finalMessage() 가 message_stop 없이 닫힌 흐름을 받은 것 — 잘린 답 */ }
}
Python 은 이 순서예요(SDK 동작 · anthropic 2.3.0 으로 확인)
import anthropic

try:
    message = client.messages.create(...)   # 스트림이면 with client.messages.stream(...) as s: 안에서 s.get_final_message()
except anthropic.APIConnectionError:
    ...  # 실행 불명 — Idempotency-Key 없이 불렀으면 자동 재전송 금지 · 실었으면 같은 Idempotency-Key · 같은 본문으로 한 번
except anthropic.APIStatusError as e:
    err = e.body.get("error", {}) if isinstance(e.body, dict) else {}   # Anthropic SDK 는 봉투 전체를 줘요
    kind, reason, s = err.get("type"), err.get("reason"), e.status_code
    no_retry = e.response.headers.get("x-should-retry") == "false"
    status_url = e.response.headers.get("x-gateway-status-url")   # 조회는 no_retry 와 같이 왔을 때만
    if s == 200: ...  # 스트림 도중 온 event: error — 잘린 답 · 받은 글로 이어 받기
    elif kind == "group_limit_exceeded": ...  # group_budget 이면 max_tokens 를 줄여 새 Idempotency-Key 로 · group_tail 이면 출력 단가가 낮은 모델로 바꿔 새 Idempotency-Key 로 · 그 밖은 멈추고 스페이스 관리자에게
    elif kind == "key_limit_exceeded" and reason != "held_by_others": ...  # key_month_limit 은 줄여 새 Idempotency-Key 로 · key_day_limit 은 한국 시간 0시까지 멈춤
    elif s == 504 and reason == "timeout": ...  # 잠시 뒤 한 번만 같은 Idempotency-Key · 같은 본문으로
    elif kind == "upstream_error" and s < 500: ...  # 모델 회사가 거절 — 문장대로 고쳐 새 Idempotency-Key 로
    elif s == 503 and kind in ("request_state_unavailable", "request_store_unavailable"): ...  # Retry-After(없으면 직접 정한 간격) 뒤 같은 Idempotency-Key 로 한 번
    elif kind in ("upstream_execution_unconfirmed", "request_already_exists") or (no_retry and status_url): ...  # 자동 재전송 금지 · status_url 을 GET 조회
    elif reason == "held_by_others": ...  # 402 · 429 — Retry-After(5초) 뒤 같은 Idempotency-Key · 같은 본문으로 그대로
    elif kind == "insufficient_credit": ...  # hold_exceeds_balance 면 max_tokens 줄이기 · below_minimum_balance 면 충전
    elif (s == 429 and kind == "rate_limit_error") or (kind == "upstream_error" and not no_retry) or (s == 503 and kind == "api_error"): ...  # 529 도 — Retry-After(없으면 직접 정한 간격) 뒤 다시
    elif no_retry: ...  # 다시 보내지 말고 문장대로 고치기(401 · 409 idempotency_conflict 등)
    elif s >= 500: ...  # 알려지지 않은 5xx — 자동 재전송하지 않고 확인
    else: ...  # 문장대로 고치기 — 사람에게 보일 문장은 err.get("message")

Idempotency-Key 는 요청마다 실어요(SDK 동작) — Python 은 client.messages.create(…, extra_headers={"Idempotency-Key": key}), Node 는 client.messages.create(params, { headers: { "Idempotency-Key": key } }) 예요. SDK 를 올려 anthropic-version 이 바뀌면 같은 값은 409 idempotency_conflict 예요. 값은 공백 · 제어문자 없는 ASCII(영문 · 숫자 · 기호) 8~200자이고, 새 요청엔 새 값을, 같은 요청을 다시 보낼 땐 같은 값을 써요. x-gateway-status-url · Location · error.status_url 은 /v1/requests/<id> 꼴의 상대 주소예요 — 앞에 https://oneport.kr 를 붙여 같은 API 키(Authorization: Bearer · x-api-key 둘 다 받아요)로 GET 해요(요금 없음 · 다른 API 키로는 404 — 「새로 받기」로 바꾼 새 API 키는 읽혀요). x-gateway-status-url 은 Idempotency-Key 를 실어 접수된 요청의 응답에 늘 와요(200 · 오류 모두 · 409 request_already_exists 도). 그중 실패 응답(422 upstream_execution_unconfirmed · 409 포함)엔 같은 값이 Location 머리글에도 오고, 몸통이 JSON 오류면 error.status_url 에도 와요(성공 응답엔 머리글에만). Idempotency-Key 없이 부른 호출엔 조회 주소가 없어요. 조회 답은 {"id", "object": "gateway.request", "execution", "http_status", "created_at", "updated_at", "result": {"state"}, "settlement": {"state", "cost_credits"}, "response_stored": false} 예요. execution 은 claimed(접수만 됐어요) · started(모델 회사로 보냈어요 — 끝까지 답한 요청도 여기예요) · not_started(모델 회사로 안 갔어요) · unknown(보냈는지 몰라요)이에요. result.state 는 unknown · completed · failed · partial, settlement.state 는 unknown · settled · not_charged 예요(settlement.cost_credits 는 unknown 이면 null). 같은 Idempotency-Key · 같은 본문으로 다시 받는 건 execution 이 not_started 일 때뿐이에요 — result.state 가 failed 여도 started 면 같은 Idempotency-Key 는 409 request_already_exists 예요. 답 본문은 다시 못 받아요. 409 request_already_exists 에도 x-should-retry: false 와 이 주소가 붙어요. 키 줄의 「새로 받기」로 바꾸면 옛 키로 받은 접수도 새 키로 옮겨져서, 같은 Idempotency-Key 를 새 키로 보내도 옛 키로 보낸 것과 같아요(끝난 접수면 409). 칸 뜻은 「요청 상태」 장이에요.

안 될 때#

  • 404 가 난다 — base_url 끝에 /v1 을 붙이셨을 거예요. SDK 가 /v1/messages 를 스스로 붙여서 두 번 붙어요. oneport.kr 까지만 적어주세요.
  • 400 이 난다 — max_tokens 를 안 보내셨을 수 있어요. Anthropic 은 이 값이 필수이고, 이 문은 번역이 없어서 저희가 채워드리지 않아요. /v1/chat/completions 쪽은 8,192 로 채워드려요. Anthropic 이 거절한 400 은 error.type 이 upstream_error 이고, 문장은 Anthropic 말 그대로 와요.
  • temperature · top_p · top_k 로 400 이 난다 — 새 판 SDK(아래 「SDK 판과 anthropic-version」)가 2026-10-21 판을 싣는데, 그 판은 세 칸을 받지 않아요. claude-haiku-4-5 · claude-sonnet-4-5 · claude-sonnet-4-6 · claude-opus-4-6 처럼 값을 읽는 모델이면 저희가 보내기 전에 400 invalid_request_error 로 막아요(요금 없음) — 빼시거나, 그 값이 꼭 필요하면 anthropic-version: 2023-06-01 을 주세요. claude-fable-5 · claude-fable-5-1 · claude-fable-5-2 · claude-opus-5 · claude-opus-5-5 · claude-sonnet-5 · claude-sonnet-5-5 · claude-haiku-5-5 · claude-opus-4-7 · claude-opus-4-8 은 값을 안 읽어서 어느 판이든 저희가 빼고 넘기고 x-gateway-ignored-params 에 적어요.
  • tool_choice 를 {"type":"any"} 나 {"type":"tool"} 로 강제했더니 400 이 난다 — claude-fable-5-2 · claude-fable-5-1 · claude-opus-5-5 · claude-sonnet-5-5 는 강제 도구 호출을 받지 않아요. "auto" 로 두시거나 다른 모델로 부르세요.
  • GPT·Gemini 를 넣었더니 400 이 난다 — 이 문은 Claude 만 받아요. 여러 벤더를 섞으시려면 /v1/chat/completions 쪽이 편해요.
  • 402 insufficient_credit — 크레딧이 모자라요. 충전하시거나 max_tokens 를 줄여 주세요(요금이 붙기 전에 막혀요). 부르기 전에 잡는 몫은 출력(max_tokens × 출력 단가)만이 아니에요 — 입력(보낸 JSON 바이트 ÷ 3 토큰 · base64 그림은 한 장에 4,800 토큰까지로)도 함께 잡아요. 셈은 (입력 토큰 × 입력 단가 + max_tokens × 출력 단가) ÷ 1,000,000 이고 단가는 GET /v1/models 의 pricing.rates 그대로예요 — pricing.tier 가 있는 모델은 어림한 입력이 above_input_tokens 이상이면 입력 · 출력 모두 tier 단가로 잡아요. 바이트는 저희가 받은 JSON 을 공백 없이 다시 적은 UTF-8 로 재요 — 한글은 한 글자 3바이트(≈ 1토큰)이고, SDK 가 \uXXXX 로 보냈어도 같아요. cache_control 이 몸통 어디에든 하나라도 있으면(맨 위 · system · messages · tools) 캐시 블록만이 아니라 입력 몫 전체를 캐시 쓰기 단가(5분은 cache_write 줄 · ttl "1h" 는 input_text 의 2배)로 잡아요 — 캐시로 읽힐 다음 호출도 같아요. 그래서 긴 문서를 실은 호출은 max_tokens 를 줄여도 402 가 날 수 있어요 — 그땐 충전해 주세요. 실제로는 쓴 만큼만 사용해요. 문장에 「다른 호출이 잡아 둔 몫」이 있으면(「크레딧이 부족해요. 다만 지금은 …」 한 줄) 잔액 문제가 아니에요 — 잠시 뒤 그대로 다시 보내거나 동시에 보내는 수를 줄여 주세요. claude-sonnet-5 · claude-opus-5-5 를 스트림 없이(stream 을 빼거나 false 로) 부를 때, 몸통이 model · messages · system · max_tokens(· stream: false)뿐이고 messages 가 글자(content 가 문자열)로 된 user 메시지 하나이며, anthropic-version 을 안 싣거나 2023-06-01 하나만 실었으면 입력 몫을 넉넉히 잡아요 — (몸통 바이트 + 16,384) 토큰 × input_text 의 2배 + max_tokens × 출력 단가예요(몸통 16KiB · max_tokens 32,768 이하일 때만 · 위 첫 예시가 이 모양이에요 · 실제로는 쓴 만큼만 사용해요 · 나머지 조건은 「남은 한도」 장). 새 판 SDK(2026-10-21)로 보낸 요청이나 PDF · 그림 · 도구 · 여러 턴을 실은 요청은 보통 셈이에요. 이 갈래면 402 문장에 「stream: true 로 보내거나」가 붙어요 — stream: true 로 보내면 보통 셈으로 잡아요.
  • 모델 회사로 보낸 뒤 시간 초과 · 연결 끊김 · 408 · 실행 전 거절이 확인되지 않은 5xx · 성공 머리글 뒤 JSON 유실은 422 upstream_execution_unconfirmed 예요. x-should-retry: false 를 따르고 자동 재전송하지 마세요. Idempotency-Key 를 실어 보낸 요청이면 받은 x-gateway-status-url 을 같은 API 키로 GET 조회하세요. Idempotency-Key 없이 보낸 요청엔 조회 주소가 안 오고 요청 ID 로 만든 주소로는 조회가 안 돼요 — 요청 ID 와 부른 시각을 admin@schoolorder.kr 로 알려 주세요. 전송 전 503 api_error 는 재시도 금지 헤더가 없을 때 Retry-After 만큼 기다렸다 다시 보내요.
  • 429 key_limit_exceeded — error.reason 으로 갈라요. key_month_limit 이면 월 한도예요 — 이 요청의 최대 몫까지 더해 재서 max_tokens 를 줄이면 통과할 수 있어요. key_day_limit 이면 하루 한도예요 — 이미 쓴 몫만으로 재서 줄여도 같고, 한국 시간 0시에 다시 열려요. 이 둘엔 x-should-retry: false 가 붙어 SDK 가 스스로 다시 보내지 않아요. held_by_others 면 같은 키로 아직 끝나지 않은 호출 몫 때문이라 x-should-retry: true · Retry-After: 5 가 붙어요 — SDK 재시도를 켜 두면 SDK 가 그만큼 기다렸다 다시 보내요(SDK 동작 · 「에러」 장).
  • 429 rate_limit_error · 529 — 모델 회사가 잠깐 몰린 거예요. Retry-After 가 있으면(1~60초) 그만큼 기다렸다 그대로 다시 보내요. 429 엔 늘 오고(모델 회사가 값을 안 주면 5초), 529 엔 Anthropic 이 값을 줬을 때만 와요 — 없으면 간격을 직접 정해요. 529 는 type 이 upstream_error 라 상태 코드로 가르세요.
  • 오류 몸통은 Anthropic 과 같은 모양({"type":"error","error":{...}})이라 SDK 오류로 그대로 잡혀요.

남은 크레딧 보기#

남은 크레딧은 GET https://oneport.kr/v1/credits 의 balance_credits, 이 키의 남은 몫은 GET https://oneport.kr/v1/key 예요(같은 키를 Authorization: Bearer 로 · 요금 없음). 정산은 답을 보낸 뒤 따로 돌아서, 답 직후엔 몇 초 뒤에 다시 보세요. balance_credits 는 1 크레딧 아래를 버리고 /v1/key 의 used_credits 는 올린 정수라, 질문 한두 번은 앞뒤 차이로 재기 어려워요. 한 호출에 쓴 양은 위 「쓴 크레딧 · 요청 ID 남기기」대로 usage.cost_credits 로 보고, 그 칸이 없을 때만 usage 토큰 × pricing.rates 단가 ÷ 1,000,000 으로 세세요. 상태 코드부터 보세요 — 401(키) · 503 api_error(잠깐 못 읽음)면 그 칸이 없어요.

원래대로 되돌리기#

base_url 줄을 지우고 키를 Anthropic 키로 바꾸시면 Anthropic 직접 연결로 돌아가요. 코드에 남는 저희 흔적은 그 두 줄뿐이에요.