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

에러

상태 코드와 대응 방법, 그리고 증상별로 찾아가는 자리.

AI 에게 넘기기ChatGPT 에서 열기 (새 창)Claude 에서 열기 (새 창)원문 열기

에러 몸통은 부르신 문의 형식을 따라요 — OpenAI 형식 문과 /v1/messages 의 모양이 다르니 파서를 짜실 때 보세요. 어느 쪽이든 type 값은 같고, 분기는 type 으로 하세요(OpenAI 형식의 code 는 type 과 같아요). 스페이스 전송 정책에 걸린 경우(type space_content_policy)만 code 에 세부 이유(blocked_term 등)가 따로 와요.

OpenAI 형식 문 (/v1/chat/completions · /v1/responses · /v1/embeddings 등)
{
  "error": {
    "type": "model_not_found",
    "message": "지원하지 않는 모델이에요: claude-sonet-5. 이건 어떠세요: claude-sonnet-5. 전체 목록은 GET /v1/models 에 있어요.",
    "code": "model_not_found"
  }
}
Anthropic 형식 문 (/v1/messages)
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "이 문은 anthropic 모델만 받아요."
  }
}
코드type다시 보내나SDK 예외 클래스뜻과 대응
400invalid_request_error고쳐서 — 문장이 고칠 곳을 말해요BadRequestError요청 형식이나 문이 안 맞아요. 파는 모델인데 문이 틀린 경우도 여기로 와요 — 그때는 어느 문으로 가야 하는지 문장에 적어 드려요.
401authentication_error고쳐서 — 키 · 머리글 · reason account_inactive 면 멈춤(문의)AuthenticationError키가 없거나 쓸 수 없는 키예요. 이유는 error.reason 으로 가르세요 — missing_key · malformed_key · unset_key · foreign_key · management_key · key_not_found · key_revoked · key_expired · account_inactive 아홉 값이고, 뜻과 할 일은 「인증」 장의 「키가 안 열릴 때」 표에 있어요. 관리 키 문 /v1/keys 의 401 은 missing_key · malformed_key(sk-so- 키를 보냈을 때도) 둘만 오고, 그 밖의 401 엔 reason 이 없어서 문장을 그대로 보여 주세요.
402insufficient_credit기다렸다(reason held_by_others · Retry-After 5초) · 고쳐서(hold_exceeds_balance — 상한을 줄여요) · 멈춤(below_minimum_balance — 충전) — SDK 는 402 를 스스로 안 보내요전용 클래스 없음 — Python APIStatusError · Node APIError크레딧이 모자라요. 부르기 전에 나오니 요금은 안 붙어요. 글 문은 error.reason(held_by_others · hold_exceeds_balance · below_minimum_balance)으로 갈래를 알려 드려요(아래 「402 는 호출 전에 나요」) — 그중 held_by_others 에만 Retry-After 가 붙고, Retry-After 가 없는 402 는 다시 보내지 말고 충전하거나 max_tokens · 한도를 고쳐요. 그림 · 소리 문도 같은 세 값이 와요(이 두 문은 held_by_others 에도 Retry-After 가 없으니 reason 으로 가르고, held_by_others 면 몇 초 쉬고 그대로 다시 보내요) — hold_exceeds_balance 면 그림은 참고 그림 · input_fidelity, 읽어주기는 글, 받아쓰기는 파일 크기(WAV 는 길이)를 줄이면 통과할 수 있어요. 임베딩 문도 세 값이 다 와요 — hold_exceeds_balance 면 묶음을 줄이고, held_by_others 엔 글 문처럼 Retry-After: 5 가 붙어요. 영상 문 402 도 held_by_others(Retry-After: 5) · hold_exceeds_balance(더 짧게 · 낮은 해상도로 고르면 지나갈 수 있어요)가 와요 — below_minimum_balance 는 영상 문엔 안 와요. 작업 문 402 는 다른 호출이 잡아 둔 몫일 때만 error.reason held_by_others(Retry-After: 5)가 와요. 충전은 키를 나눠 받으셨으면 키를 준 분(지갑 주인)께 부탁하고, 직접 만든 키면 키를 받은 메일로 https://oneport.kr/buy 에서 사요(다른 메일로 사면 다른 지갑에 들어가요) — API 키의 402 문장 끝도 이렇게 누가 충전할지를 말해요.
403model_not_in_plan고쳐서 — 문장이 준 모델로PermissionDeniedError이 크레딧으로 못 부르는 모델이에요 — 제미나이는 제미나이 팩이나 모델을 정하지 않은 크레딧으로 불러요. 요금이 붙기 전에 나고, 바꿔 넣을 모델 이름을 문장에 같이 드려요.
403student_key_blocked고쳐서 — 문장이 말한 도구 · 칸을 빼거나 모델을 바꿔요PermissionDeniedError학생 키로 웹 검색 · 웹 페이지 읽기 · 다른 서버의 도구(원격 MCP) · 영상 만들기 · jev · 작업(/v1/tasks)을 불렀어요(검색이 붙은 모델 · web_search_options 같은 검색 칸 포함). 요금이 붙기 전에 나고, 빼야 할 도구 · 칸 이름이나 바꿔야 할 모델을 문장에 적어 드려요. Codex CLI 는 웹 검색을 늘 실어 보내니 web_search = "disabled" 로 꺼 주세요. 키를 나눠 준 분이 그 키를 선생님 키로 바꾸면 열려요.
403model_disabled_in_space고쳐서 — 켜진 모델로PermissionDeniedError스페이스 관리자가 끈 모델이에요. 키가 붙은 그룹에서만 끈 모델도 이 type 이고, 그때는 그룹 이름을 문장에 적어 드려요. 요금이 붙기 전에 나고, 켜진 모델 이름을 문장에 같이 드려요. 내 키로 GET /v1/models 를 부르시면 켜진 모델만 나와요.
403student_cannot_request멈춤 — 학생 키로는 부탁할 수 없어요 · 선생님께PermissionDeniedError학생 키로 커넥터 부탁 문 · 부탁 목록 · 한 줄 조회(/v1/connectors/requests …)를 불렀어요. 학생은 선생님께 말해요 — 키를 나눠 준 분이 그 키의 쓰임새를 「선생님」으로 바꾸면 같은 키로 다음 요청부터 부탁할 수 있어요. GET /v1/connectors 는 학생 키로도 불러요(줄의 reason 칸은 지갑 관리자가 막은 줄 blocked_by_admin · 저희가 부탁을 막은 줄 not_verified 말고는 모두 student_blocked). 내 키가 학생 키인지는 GET /v1/key 의 audience 가 "student" 인지로 봐요(요금 없음). 「커넥터」 장(https://oneport.kr/docs/reference/connectors.md).
403connector_unavailable멈춤 — error.reason 대로: blocked_by_admin 이면 지갑 관리자와 함께 원포트(admin@schoolorder.kr)에 물어요. 그분이 정하는 화면은 아직 손님께 열리지 않았어요 · not_verified 면 원포트(admin@schoolorder.kr)에 물어요 · declined 면 error.connector_request_id 의 부탁 줄 message 로 까닭을 봐요(물을 곳도 원포트예요)PermissionDeniedError커넥터 부탁 문(POST /v1/connectors/requests)에서 부탁할 수 없는 서비스예요. error.reason 이 누구에게 물을지 알려 줘요. blocked_by_admin 이면 지갑 관리자가 막은 거예요. 지갑 관리자와 함께 원포트(admin@schoolorder.kr)에 물어요. 그분이 정하는 화면은 아직 손님께 열리지 않았어요. 지갑 관리자는 스페이스가 아닌 지갑이면 지갑 주인(구성원은 못 해요), 스페이스 지갑이면 스페이스 주인 · 관리자예요. not_verified · declined 면 admin@schoolorder.kr 로 저희(원포트)에 물어요. declined · not_verified 는 이 지갑에서 앞서 낸 같은 서비스 부탁이 닫힌 거라 그 부탁 줄 id(error.connector_request_id)가 늘 오고, 이번 요청으로 새 줄은 안 생겨요. declined 는 늘 저희(원포트)가 다시 부탁할 수 없게(can_request_again false) 거절한 거예요 — 지갑 관리자 거절은 403 이 아니라 다시 부탁돼요. not_verified 는 그 부탁을 저희가 막았을 때(부탁 state blocked)만 와요 — 아직 안 연 서비스는 부탁하면 받아요(새 부탁이면 201 received). blocked_by_admin 엔 id 가 없고, 그 message 는 정해진 안내 문장이에요 — 지갑 관리자가 막은 까닭은 API(이 403 · GET /v1/connectors · 부탁 줄)로 오지 않아요. declined · not_verified 의 까닭은 error.connector_request_id 로 GET /v1/connectors/requests/{id} 를 읽어 message 로 봐요 — declined 면 늘 있고, not_verified 는 저희가 까닭을 적었을 때만 있어요. 「커넥터」 장(https://oneport.kr/docs/reference/connectors.md).
404model_not_found고쳐서 — GET /v1/models 의 id 로NotFoundError그 이름의 모델이 없어요. 응답에 가장 가까운 이름을 같이 드려요. 모델 목록을 잠깐 못 읽으면 404 가 아니라 503 api_error(Retry-After: 2)예요 — 404 면 이름을 고쳐요.
404not_found_error고쳐서 — 문장이 맞는 주소를 알려 줘요NotFoundError없는 주소예요. 문장에 고칠 방법(/v1 두 번 · 옛 completions · 묶음 처리 등)을 적어 드려요. 묶음 처리 문(/v1/batches)은 없어요 — 여러 건은 한 건씩 보내 주세요(동시에 보내셔도 돼요 · 지갑 몫은 아래 「402 는 호출 전에 나요」). 커넥터 부탁 한 줄 조회(GET /v1/connectors/requests/{id})에선 id 가 UUID 꼴이 아니거나 이 지갑의 부탁이 아닌 거예요.
429key_limit_exceeded기다렸다(reason held_by_others — 같은 API 키로 보낸, 아직 끝나지 않은 다른 호출이 잡아 둔 몫 · Retry-After 5초 · x-should-retry: true 라 SDK 재시도를 켜 두면 SDK 가 해요) · 고쳐서(key_month_limit — 상한을 줄여요 · 안 되면 한도를 올리거나 한국 시간 다음 달 1일 0시 · 시각은 error.resets_at) · 멈춤(key_day_limit — 한국 시간 내일 0시에 다시 열려요 · 시각은 error.resets_at · 이미 쓴 몫만 재서 닿기 전에 보낸 호출(동시에 보낸 것 포함)은 다 지나가 그만큼 넘을 수 있어요 — 「남은 한도」 장) — key_month_limit · key_day_limit 은 x-should-retry: false 라 SDK 도 안 보내요RateLimitError(세 갈래 다 — type 으로 갈라요)그 키의 이번 달 한도나 오늘 한도에 닿았어요. 글 문(/v1/chat/completions · /v1/messages · /v1/responses)과 임베딩 · 그림 · 소리 · 영상 · 작업 문은 error.reason 으로 갈래를 알려 드려요 — key_month_limit 이면 이번 달 한도, key_day_limit 이면 하루 한도, held_by_others 면 이번 달 한도인데 같은 키로 아직 끝나지 않은 호출 몫 때문이에요(2026-10-30 부터). hold_exceeds_key_limit 은 학교 지갑의 학생 API 키에서 이 요청 하나가 미리 잡는 몫만으로 월 한도보다 큰 거예요 — 쓴 몫과 상관없이 max_tokens 를 줄이거나 더 가벼운 모델로 바꿔야 지나가요(문장은 key_month_limit 과 같아요 · 2026-10-31 부터). 작업 문(/v1/tasks)은 처음 응답에만 와요 — 같은 Idempotency-Key 로 다시 조회한 응답엔 reason · resets_at 이 없고 문장도 「사용 한도에 닿아」 하나라 하루 · 월을 못 가르니, 처음 응답의 reason 을 보관하세요. 이번 달 한도는 「쓴 몫 + 이 키로 아직 끝나지 않은 몫 + 이 요청이 최대로 쓸 몫」으로 재서, 남은 몫이 있어도 max_tokens 가 크면 막히고 줄이면 통과할 수 있어요(임베딩은 묶음 · 읽어주기는 글 · 받아쓰기는 파일 크기(WAV 는 길이) · 영상은 길이(seconds)나 해상도 · 그림 고치기는 참고 그림(둘째 장부터) 수나 input_fidelity 를 줄여요 · 그림 만들기는 한 장 몫이라 줄일 칸이 없어요). 하루 한도는 이미 쓴 몫만 봐서 max_tokens 를 줄여도 같아요. 다시 열리는 시각은 몸통의 error.resets_at 에 와요 — 하루 한도는 한국 시간 0시, 이번 달 한도는 다음 달 1일 0시예요(2026-11-02 부터 · GET /v1/key 의 month.resets_at · day.resets_at 과 같은 값 · UTC ISO 시각 — 예: 2026-10-26T15:00:00.000Z 가 한국 시간 27일 0시예요. remaining_credits 는 1 크레딧 아래를 버린 정수예요). hold_exceeds_key_limit · held_by_others 는 null 이고, Retry-After 로는 주지 않아요. 대시보드에서 올리시면 바로 풀려요. key_month_limit · key_day_limit 은 그대로 다시 보내면 같아서 x-should-retry: false 가 붙어요. held_by_others 는 아래 「held_by_others — 기다리면 풀리는 402 · 429」예요. 다만 문장에 「미리 잡는 몫 대부분이 입력」이 붙었으면 줄여도 거의 안 줄어요 — 첨부 · 대화 기록을 줄이거나 나눠 보내 주세요(주소로 붙인 문서가 있으면 문장이 문서를 base64 로 넣어 보내라고 해요). 분당 제한은 저희가 안 걸어요.
429rate_limit_error기다렸다 — 글 문 · 토큰 세기 문 · 임베딩 문은 Retry-After 가 늘 붙으니 그만큼(벤더가 준 값을 1~60초로 맞추고, 벤더 값이 없으면 5초) · SDK 재시도를 켜 두면 SDK 가 해요RateLimitError(세 갈래 다 — type 으로 갈라요)벤더가 조였고, 글 문은 같은 모델의 다른 경로까지 다시 걸어 봤는데도 막혔어요. 키 한도와 달리 잠시 뒤 다시 보내면 돼요 — 글 문은 이 429 에 Retry-After(초)가 늘 붙어요: 벤더가 알려 준 값(1~60초로 맞춰요)이고, 벤더가 값을 안 줬으면 저희가 5초로 채워요(값은 늘 정수 초예요). 그만큼 기다렸다 같은 요청을 보내세요(그림 · 소리 · 임베딩 문은 다른 경로로 다시 걸지 않고 바로 429 rate_limit_error 로 드려요 — 이것도 잠시 뒤 다시 · 임베딩 문엔 2026-10-30 부터 같은 규칙으로 Retry-After 가 오고, 그림 · 소리 문엔 없어요). 토큰 세기 문(/v1/messages/count_tokens)의 429 에도 같은 규칙으로 Retry-After 가 와요(2026-10-29 부터). 429 upstream_error 는 오지 않아요. 저희 쪽 사정(모델 회사와의 결제 · 할당량)으로 거절된 429 는 이 type 이 아니라 503 api_error(error.reason provider_unavailable)로 드려요.
429group_limit_exceeded고쳐서(reason group_budget — GET /v1/key 의 group.remaining_credits 가 0 보다 크면 상한을 줄여요 · 오류 몸통엔 이 칸이 없어요 · group_tail — 글 문은 모델을 바꿔요) · 멈춤(group_budget 인데 남은 몫 0 · group_closed 닫힌 강좌 · group_not_started · group_ended 반 기간 밖) — SDK 도 안 보내요 · 스페이스(강좌 · 반 · 부서)에 붙은 키에서만 와요RateLimitError(세 갈래 다 — type 으로 갈라요)스페이스 강좌 몫으로는 이 요청을 보낼 수 없거나 강좌가 닫혔어요. 그대로 다시 보내면 안 풀려요(x-should-retry: false). 갈래는 error.reason 으로 와요(글 문 · 임베딩 · 그림 · 소리 · 영상 · 작업 문 — 작업 문(/v1/tasks)은 처음 응답에만). group_budget 은 「쓴 몫 + 이 요청이 최대로 쓸 몫」이 강좌 몫을 넘은 거예요 — 남은 몫이 있어도 올 수 있어서, GET /v1/key 의 group.remaining_credits 가 0 보다 크면 출력 상한(글 문은 max_tokens · 임베딩은 묶음 · 읽어주기는 글 · 받아쓰기는 파일 크기(WAV 는 길이) · 영상은 길이(seconds)나 해상도 · 그림 고치기는 참고 그림(둘째 장부터) 수나 input_fidelity — 그림 만들기는 한 장 몫이라 줄일 칸이 없어요)을 줄여 보내 보세요(0 이면 줄여도 안 돼요). group_closed 는 관리자가 강좌를 닫은 거라(group.closed 가 true) 스페이스 관리자에게 말해 주세요. group_not_started 는 반(기수) 시작일 전, group_ended 는 반 기간이 끝난 거예요. group_budget 말고 셋은 줄여도 안 풀려요. group_tail 은 회사·기관 부서 몫의 끝(관리자가 정한 비율 · 켜면 5%)에서 크레딧을 많이 쓰는 요청만 막은 거예요(남은 몫이 있어도 와요). 글 문은 출력 단가(GET /v1/models 의 pricing.output_credits_per_mtok)가 claude-sonnet-5-5 의 절반 이하인 모델로 바꾸면 보내지고(목록 값은 소수 둘째 자리로 반올림돼 있어, 절반과 0.01 안쪽으로 붙은 모델은 보내 봐야 갈려요), 그림 · 영상 · 작업 문은 다음 달 1일에 다시 열려요(임베딩 · 소리 문엔 안 와요). 반(기수) 기간 밖이면 다시 보내지 말고 강사님이나 담당자에게 말해 주세요. error.resets_at 은 매달 채워지는 몫의 group_budget · group_tail 이면 다음 달 1일 0시, group_not_started 면 반 시작일 0시이고, 다시 안 열리면 null 이에요. 문장에 「미리 잡는 몫 대부분이 입력」이 붙었으면 출력 상한을 줄여도 거의 안 줄어요 — 첨부 · 대화 기록을 줄이거나 나눠 보내 주세요(키 한도와 같아요). 모르는 reason 이 오면 문장으로 갈라요(아래 감싸개).
429group_member_limit_exceeded멈춤 — 웹 채팅 몫이에요RateLimitError(세 갈래 다 — type 으로 갈라요)웹 채팅에서 강좌 안 내 몫(1인 몫)에 닿았어요. 다시 보내도 안 풀려요(x-should-retry: false). API 키에는 안 와요 — API 키의 한 사람 몫은 키의 이번 달 · 오늘 한도(key_limit_exceeded)예요.
429too_many_open멈춤 — 앞의 작업이 닫히거나 기다리던 부탁의 결과가 나온 뒤에 · x-should-retry: false 예요RateLimitError(세 갈래 다 — type 으로 갈라요)열어 둔 것이 상한에 닿았어요 — 작업 문(POST /v1/tasks)은 이 키에서 열린 작업, 커넥터 부탁 문(POST /v1/connectors/requests)은 이 지갑에서 결과를 기다리는(received · reviewing) 부탁 20건이에요. 커넥터 부탁은 같은 지갑의 다른 API 키가 낸 것도 같이 세요. x-should-retry: false 라 바로 다시 보내도 같아요. 앞의 작업이 닫히거나 부탁의 결과가 나온 뒤 다시 보내요 — 작업 문의 Idempotency-Key 규칙은 「작업」 장이에요.
4xx · 5xxupstream_error고쳐서(요청 거절 4xx) · 기다렸다(x-should-retry: false 없이 온 5xx — 간격은 Retry-After, 없으면 코드가 정해요 · 완전한 본문으로 확인된 Anthropic overloaded_error 만 529 로 와요) · 멈춤(x-should-retry: false 가 붙은 것 — 이게 먼저예요 · 504 error.reason timeout 은 요금 없이 끝난 거라 직접 한 번 다시 보내도 돼요 — Idempotency-Key 를 실었으면 같은 Idempotency-Key 로)상태대로 — 5xx 는 InternalServerError(Python anthropic 은 529 가 OverloadedError)벤더가 요청을 거절했어요. 글 문(/v1/chat/completions · /v1/messages · /v1/responses)은 실행 전 거절이 확인된 4xx 를 같은 상태로 돌려드려요(429 는 rate_limit_error). 요청을 고쳐 주세요. 모델 회사가 내용(안전 · 정책) 문제로 거절한 403 · 400 도 이 type 으로 와요 — 같은 요청을 다시 보내도 같아요. 저희 쪽 사정으로 모델 회사가 요청을 받지 않은 실패는 503 api_error(error.reason provider_unavailable)로 와요(아래 줄). 예외로 완전한 응답 본문의 Anthropic overloaded_error 는 실행 전 과부하 거절로 확인해 다음 경로를 시도하며, 모두 거절하면 원래 5xx upstream_error 를 드릴 수 있어요. 모델 회사가 준 529 상태만으로는 이 예외가 아니에요 — 이렇게 확인된 과부하만 529 로 오고, 이 529 엔 Claude 가 기다릴 시간을 알려 줬을 때만 Retry-After(1~60초로 맞춰요)가 붙어요. 529 의 type 은 overloaded_error 가 아니라 upstream_error 라 상태 529 로 가르세요. x-should-retry: false 없이 온 529 · 5xx upstream_error 는 실행 전 거절이 확인된 것이라 기다렸다 같은 요청을 보내도 돼요(Idempotency-Key 를 실었으면 같은 키로). 모델 회사로 보낸 뒤 연결 끊김 · 시간 초과 · 408 · 실행 전 거절이 확인되지 않은 5xx(500 · 503 · 529 포함)와 성공 머리글 뒤 JSON 유실은 422 upstream_execution_unconfirmed 로 가요 — 이 경우를 5xx 재시도로 처리하지 마세요. 실행 전 거절로 다른 경로를 도는 사이 합쳐 4분 기한을 넘기면 504 upstream_error(error.reason "timeout" · x-should-retry: false)로 와요 — 모델 회사에서 실행되기 전에 끝난 실패라 요금은 없어요. 그림 · 소리 · 임베딩 · 검열 등 다른 문의 upstream_error 상태와 재시도는 각 레퍼런스의 별도 규칙을 따르세요.
400 · 403 · 409 · 503space_content_policy고쳐서(400 · 403 — content_limit 은 나눠서) · 그대로 한 번(409 policy_changed) · 기다렸다(503 policy_unavailable)BadRequestError · PermissionDeniedError · ConflictError · InternalServerError스페이스 전송 정책에 걸렸어요. 이유는 code 에 와요 — blocked_term · policy_forbidden · unsupported_capability 는 403, invalid_content · content_limit 은 400 이에요(그대로 다시 보내면 같아요). blocked_pii(403)는 「차단」으로 정한 개인정보 종류가 마지막 user 글에 있는 거예요 — 종류는 error.reason(resident · mobile · landline · email · card · biz · driver)에 와요. 그 글을 지우고 다시 보내요. content_limit 은 대개 한 요청에 담은 글이 너무 많은 거예요 — 문장이 「한 번에 보내는 글이 너무 많아요. 나눠서 보내 주세요.」이고, 대화 기록 · 붙인 글 · 임베딩 묶음을 나눠서 보내면 풀려요. 도구 정의처럼 너무 깊게 겹친 JSON 도 같은 code 라, 그땐 나누지 말고 구조를 얕게 해 주세요. policy_changed(409)는 정책이 방금 바뀐 것이라 그대로 한 번 다시 보내시면 바뀐 정책으로 다시 검사해요(벤더로 보내기 전이라 요금은 안 붙어요). policy_unavailable(503)은 정책을 못 읽은 것이라 잠시 뒤 다시 보내시면 돼요. 이 응답들엔 x-should-retry 가 안 붙어서 Anthropic · OpenAI SDK 가 409 · 503 을 스스로 다시 보내요(SDK 동작).
422upstream_execution_unconfirmed멈춤 — 실행됐는지 몰라요 · Idempotency-Key 를 실었으면 받은 x-gateway-status-url 로 GET 조회, 안 실었으면 요청 ID 와 부른 시각으로 문의UnprocessableEntityError모델 회사로 보낸 뒤 실행 결과를 확인하지 못했어요. x-should-retry: false 가 붙고 Retry-After 는 없어요. 자동으로 다시 보내지 마세요 — Idempotency-Key 를 실었어도 새 키로 다시 보내지 마세요. x-gateway-status-url 은 Idempotency-Key 를 실은 요청에만 와요 — /v1/requests/<id> 꼴 상대 주소라 앞에 https://oneport.kr 를 붙여 같은 API 키로 GET 조회하고, 없으면 요청 ID(request-id · x-request-id · error.request_id)와 부른 시각으로 문의해 주세요. 일반 요청 ID만으로 상태 조회 주소를 만들지 마세요. 이 422 엔 요금이 안 붙어요 — 다만 모델 회사에서 실행되지 않았다는 뜻은 아니에요. 사람이 상태를 보고 다시 보내기로 했으면 Idempotency-Key 를 새로 만들어 보내요(같은 키는 409 request_already_exists 예요). 다시 보낸 요청 몫만 사용돼요 — 앞 요청이 모델 회사에서 이미 실행됐다면 같은 일이 두 번 돈 거예요(두 번 사용되지는 않아요). 422 upstream_error 는 벤더가 요청을 거절한 경우라 요청을 고쳐야 해요.
422school_guard_blocked고쳐서 — 표현을 바꿔요 · x-should-retry: falseUnprocessableEntityError학생 키로 보낸 글이 유해 문장 검사에 걸려 모델로 보내지 않았어요. 요금은 안 붙어요. 자해에 관한 글이면 문장이 자살예방상담전화 109 를 알려 드려요.
503api_error기다렸다 — 글 문 · 토큰 세기 문 · 임베딩 문 · 영상 만들기 문 · 조회 문(/v1/credits · /v1/key · /v1/models) · 관리 키 문(/v1/keys)은 Retry-After 2초(reason provider_unavailable 도 같아요 — 키를 잠깐 못 읽은 503 과 할 일이 같아요) · SDK 재시도를 켜 두면 SDK 가 해요 · 커넥터 문(/v1/connectors …)엔 Retry-After 도 x-should-retry 도 없어 몇 초 쉬고 다시(POST 는 같은 Idempotency-Key · 같은 본문으로)InternalServerError저희 쪽 일시 장애예요(벤더로 보내기 전). error.reason 이 provider_unavailable 이면 저희 쪽 사정으로 모델 회사가 이 요청을 받지 않은 거예요(실행 전 거절이 확인된 경우 · 글 문과 임베딩 문 · 영상 만들기 문 · 그림 · 소리 · 검열 문(2026-10-31 부터) — 영상은 그 작업이 요금 없이 닫혀서 같은 Idempotency-Key 로 다시 보내면 새로 만들어요). 손님 키나 요청 문제가 아니며, 이 경우에는 요금이 붙지 않았고 잠시 뒤 다시 보낼 수 있어요. 모델 회사로 보낸 뒤 실행 여부를 모르는 실패는 이 503 이 아니라 422 upstream_execution_unconfirmed 예요. error.reason 이 dispatch_unavailable 이면 Idempotency-Key 를 실은 요청을 모델 회사로 보내기 직전에 저희가 시작 기록을 못 적은 거예요 — 모델 회사로는 안 갔고 요금도 없어요(같은 Idempotency-Key 로 다시 보내는 법은 아래 「Idempotency-Key 를 실었을 때」). API 키나 잔액을 잠깐 못 읽었을 때도 이것이에요(「지금 이 키를 확인하지 못했어요」 · 「지금 잔액을 읽지 못했어요」). GET /v1/models · /v1/models/{id} 는 모델 단가표를 잠깐 못 읽었을 때도 이것이에요(2026-11-01 부터 — 예전엔 200 빈 목록 · 404 model_not_found 로 와서 부를 모델이 없는 줄로 보였어요). 모델을 부르는 문(글 문 · 토큰 세기 문 · 검열 · 임베딩 · 그림 · 소리 · 영상)은 모델 목록을 잠깐 못 읽었을 때도 이것이고 Retry-After: 2 가 붙어요(2026-10-31 부터 · 예전엔 404 model_not_found — advisor 조언 모델은 400 — 였어요). 잠시 후 다시 시도해주세요 — x-should-retry 가 안 붙어서 SDK 가 알아서 다시 보내요(API 키를 잠깐 못 읽은 「지금 이 키를 확인하지 못했어요」는 Idempotency-Key 를 실은 글 문 요청과 상태 조회 GET 에도 Retry-After: 2 가 붙고 조회 주소 없이 와요 — 접수 전이라 글 문이면 같은 Idempotency-Key · 같은 본문으로, 상태 조회면 같은 주소를 다시 GET 해요 · 아래 「Idempotency-Key 를 실었을 때」). 글 문과 토큰 세기 문(/v1/messages/count_tokens)은 Retry-After: 2(초)가 붙어요(임베딩 문 · 영상 만들기 문도 2026-10-29 부터 같아요 · 조회 문(GET /v1/credits · /v1/key · /v1/models) · 관리 키 문(/v1/keys)은 2026-11-01 부터 · 소리 · 검열 문은 provider_unavailable 503 에만 2026-10-31 부터 · 그림 문의 provider_unavailable 503 엔 없어요) — SDK 재시도를 켜 두셨으면 SDK 가 그 값만큼 기다렸다 다시 보내요(SDK 동작). max_retries(maxRetries)를 0 으로 두셨으면 그만큼 기다렸다 직접 다시 보내 주세요(아래 감싸개의 call() 이 해요).
503school_guard_unavailable기다렸다 — 몇 초 쉬고 그대로(SDK 재시도를 켜 두면 SDK 가 해요) · 글이 길어 못 본 것은 x-should-retry: false 라 나눠 보내요InternalServerError학생 키로 보낸 글을 검사하지 못해 모델로 보내지 않았어요. 요금은 안 붙어요.

「다시 보내나」는 넷 중 하나예요 — 그대로(바로 같은 요청) · 고쳐서(문장대로 고친 요청) · 기다렸다(잠시 뒤 같은 요청) · 멈춤(다시 보내지 말고 충전 · 날짜 · 문의). Idempotency-Key 를 실은 요청은 「그대로」 · 「기다렸다」면 같은 키 · 같은 본문으로, 「고쳐서」면 새 키로 보내요 — 같은 키로 본문을 바꾸면 409 idempotency_conflict 예요(아래 「Idempotency-Key 를 실었을 때」). 표 밖 type 은 이것 말고도 셋이에요 — 409 request_already_exists(멈춤 · 받은 x-gateway-status-url 을 GET) · 503 request_state_unavailable · request_store_unavailable(기다렸다 · 같은 키 · 같은 본문). 키 꼴이 틀리면 400 invalid_request_error 예요. x-should-retry: false 는 같은 요청을 그대로 되풀이하지 말라는 뜻이에요 — 문장대로 고친 요청(max_tokens 를 줄인 요청 등)은 새 요청이라 보내도 되고, 막은 조건이 풀린 뒤(앞 호출이 끝남 · 충전 · 한도를 올림) 같은 요청을 직접 한 번 보내는 것도 돼요. 작업 문(/v1/tasks)은 거절이 대개 그 Idempotency-Key 에 남아서 이때 새 키로 보내요(갈래는 「작업」 장 표). 「SDK 예외 클래스」는 openai · anthropic SDK 의 Python · Node 가 같은 이름을 써요 — Python 은 except openai.RateLimitError as e:, Node 는 err instanceof OpenAI.RateLimitError 예요(anthropic 도 anthropic.RateLimitError · Anthropic.RateLimitError). 모두 Python APIStatusError · Node APIError 의 자식이고, 402 처럼 전용 클래스가 없는 상태는 그 부모로 와요(Python anthropic 은 413 RequestTooLargeError · 529 OverloadedError 가 더 있어요). 한 클래스에 갈래가 여럿이라(429 RateLimitError 는 키 한도 · 벤더 혼잡 · 강좌 몫) 클래스만으로 다시 보내면 안 돼요 — 클래스로 받고 type · error.reason 으로 가르세요. openai · anthropic SDK 기본 재시도는 x-should-retry 를 먼저 따르고, 그 머리글이 없으면 408 · 409 · 429 · 5xx 만 다시 보내요 — 402 는 안 보내요(AI SDK 는 머리글을 안 봐요). (SDK 동작)

칸이 늘어도 깨지지 않게 — 호환 약속#

있는 칸의 이름 · 뜻과 오류 type · error.reason 값의 뜻은 바꾸지 않아요(문서와 코드가 어긋난 걸 바로잡을 땐 문서에 적힌 쪽으로 맞춰요). 대신 늘 수는 있어요 — 응답 · 오류 몸통의 칸, error.type · error.reason 의 새 값, GET /v1/models 의 칸과 pricing.rates 의 dimension, 스트림 조각 · 이벤트 종류, 응답 머리글. 그래서 모르는 칸은 건너뛰게 짜 주세요(스키마 검사를 쓰시면 모르는 칸을 막지 마세요), 모르는 값은 switch 의 기본 갈래로 보내 주세요 — 모르는 type 은 자동 재전송하지 말고 상태 조회나 문의로 확인하기(4xx 는 문장을 읽고 고칠 곳을 확인), 모르는 reason 은 문장으로 가르시면 돼요. 아래 감싸개도 그렇게 짜여 있어요.

402 는 호출 전에 나요#

게이트웨이는 부르기 전에 이 요청이 최대로 쓸 금액을 미리 잡아둬요. 잔액이 그보다 적으면 벤더로 보내지 않고 402 를 돌려줘요. 그래서 max_tokens 를 크게 잡으면 잔액이 남아 있어도 막힐 수 있어요. 402 는 error.reason 으로 셋을 갈라요(글 문 402 엔 늘 와요 — 아래 표). 문장으로도 갈려요.

  • 「이 요청에 필요한 크레딧이 부족해요(최대 …)」 — 이 요청의 최대 몫이 잔액보다 커요. 괄호 안은 입력 몫까지 든 그 최대 몫이라(1,234 크레딧처럼 쉼표를 넣은 정수 크레딧 · 올림) 잔액(GET /v1/credits)과 견줘 얼마나 줄일지 어림해요. max_tokens(/v1/responses 는 max_output_tokens — 문장도 그 이름으로 와요)를 줄이면 통과할 수 있어요(/v1/responses 몸통에 max_output_tokens 가 없으면 문장은 줄이라는 말 대신 충전을 말하고, 끝에 새 대화 안내나 아래 「미리 잡는 몫 대부분이 입력」 안내가 붙어요). 줄여도 남으면 잔액이 모자란 거라 충전해야 풀려요(https://oneport.kr/buy). max_tokens 를 안 적으면 답 하나를 8,192 토큰으로 잡아요(보낸 몸통은 3바이트를 1토큰으로) — 셈은 「남은 한도」 장에 있어요. claude-sonnet-5 · claude-opus-5-5 를 스트림 없이 user 메시지 하나(글만 · system 은 같이 있어도 돼요)로 부르면 입력 몫을 크게 잡아요(「남은 한도」 장의 지갑 특례 — anthropic-version · anthropic-beta · openai-beta 머리글을 안 실었거나 anthropic-version: 2023-06-01 하나만 실었을 때만이에요). 그래서 max_tokens 를 줄여도 402 가 남을 수 있어요 — stream: true 로 보내면 보통 셈으로 잡아요. 이 경우엔 402 문장에 「stream: true 로 보내거나」가 들어 있으니 코드에서는 그 낱말로 가르세요 — 입력 여유분이 몫의 대부분이면(짧은 질문 등) 문장에 「max_tokens 를 줄여도 거의 안 줄어요」도 붙어요. 스트림을 못 쓰는 도구(구글 시트 · n8n 등)면 이 두 모델 말고 가벼운 모델로 바꾸거나 충전하면 풀려요(문장 끝에도 이 안내가 붙어요). 문장에 「미리 잡는 몫 대부분이 입력」이 붙었으면 PDF 같은 큰 첨부 · 긴 대화 기록 때문이라 max_tokens 를 줄여도 거의 안 줄어요 — base64 PDF 는 쪽 수가 아니라 바이트로 어림해서 실제보다 훨씬 크게 잡힐 수 있어요. 잔액이 작으면 PDF 를 줄이거나 쪽을 나눠 보내 주세요. 주소(URL)로 붙인 문서는 크기와 상관없이 모델 창 하나만큼 잡아서 줄이거나 나눠도 안 줄어요 — 그땐 문장 끝도 첨부를 줄이라는 대신 문서를 base64 로 넣어 보내라고 해요(「남은 한도」 장 「최대 몫」).
  • 「크레딧이 부족해요. 다만 지금은 잔액이 모자란 게 아니라 같은 지갑의 다른 호출이 잡아 둔 몫 때문이에요 …」 — 잔액으로는 이 요청이 들어가는데, 지금 진행 중인 다른 호출이 미리 잡아 둔 몫을 빼면 모자란 거예요. 그 호출의 답이 끝까지 흐르고 정산되면 풀리니(글 문은 그 호출을 보낸 때부터 약 13분을 넘지 않아요 — 영상 · 작업 문 호출이 잡은 몫은 그 일이 끝나야 풀려서 더 길 수 있어요) 충전하거나 max_tokens 를 줄이지 말고 잠시 뒤 그대로 다시 보내 주세요(요금은 안 붙어요). 이 402 엔 Retry-After: 5(초)가 붙어요 — 적어도 그만큼 기다렸다 같은 요청을 보내고, 앞 호출이 끝날 때까지 길게는 몇 분 기다려 보세요 — 몇 번 만에 포기하고 건너뛰지 마세요(아래 감싸개 call() 은 이 갈래만 retries 와 따로 Retry-After 5초부터 6 · 12 · 24초, 그 뒤로는 30초씩 쉬며 약 13분까지 기다리고, 그래도 안 풀리면 OnePortError(action "retry_later")로 올려요 — 그 건은 버리지 말고 나중에 다시 보내세요). 여러 건을 동시에 보내실 때 나요 — 자주 나면 동시에 보내는 수를 줄여 주세요. GET /v1/credits 의 balance_credits 는 잡아 둔 몫을 빼지 않은 값이라 이 경우를 미리 가를 수 없어요(「남은 한도」 장).
  • 「크레딧이 부족해요.」로 시작하고 「(최대 …)」 · 「다른 호출이 잡아 둔 몫」이 없는 것(error.reason below_minimum_balance) — 잔액이 최소치(약 0.77 크레딧)보다 적어요. 충전해야 풀려요 — 문장 끝이 누가 충전할지를 말해요: 키를 나눠 받으셨으면 키를 준 분(지갑 주인)께 부탁하고, 직접 만든 키면 키를 받은 메일로 https://oneport.kr/buy 에서 사요(다른 메일로 사면 다른 지갑에 들어가요).
error.reason문장 머리할 일
held_by_others「크레딧이 부족해요. 다만 지금은 … 다른 호출이 잡아 둔 몫 …」Retry-After(5초)만큼 기다렸다 그대로 다시 보내요(충전 · 줄이기 아님 · 아래 「held_by_others — 기다리면 풀리는 402 · 429」).
hold_exceeds_balance「이 요청에 필요한 크레딧이 부족해요(최대 …)」max_tokens(또는 max_output_tokens)를 줄여 보내 보고, 그래도 남으면 충전해요. 문장에 「stream: true 로 보내거나」가 있으면 stream: true 로, 「출력 상한이 없는 요청은」이 있으면 출력 상한을 적어 보내요.
below_minimum_balance「크레딧이 부족해요.」로 시작 · 「(최대 …)」 · 「다른 호출이 잡아 둔 몫」 없음충전해요 — 키를 나눠 받았으면 키를 준 분께, 직접 만든 키면 키를 받은 메일로(https://oneport.kr/buy).

type 은 모두 insufficient_credit 이에요. 코드에서 가르실 땐 위 표의 error.reason 을 먼저 보세요(reason 은 글 문 /v1/chat/completions · /v1/messages · /v1/responses 와 그림 · 소리 · 임베딩 · 영상 문에 와요 · Node Anthropic SDK 면 err.error.error.reason). 앞으로 다른 값이 더해질 수 있으니 모르는 값은 문장으로 가르세요. reason 이 없으면 message 에 「다른 호출이 잡아 둔 몫」이 있는지 먼저 보고 — 있으면 잠시 뒤 그대로 다시 보내요(이 갈래 문장은 어느 문이든 「크레딧이 부족해요. 다만 지금은 …」 한 줄이라, 「크레딧이 부족해요.」 머리만 보고 충전으로 가르면 안 돼요). 없고 message 가 「이 요청에 필요한」으로 시작하면 max_tokens(또는 max_output_tokens)를 줄여 다시 보내 보시고, 아니면 충전해야 풀려요. 그림 · 소리 · 임베딩 문의 hold_exceeds_balance 는 문장이 「크레딧이 부족해요.」로 시작하고 줄일 것(참고 그림 · input_fidelity · 글 · 파일 길이 · 묶음)을 알려 줘요.

held_by_others — 기다리면 풀리는 402 · 429#

error.reason 이 "held_by_others" 면 402 insufficient_credit 이든 429 key_limit_exceeded 든 할 일이 같아요 — 아직 끝나지 않은 다른 호출이 잡아 둔 몫 때문이라 그 호출이 끝나면 풀려요. 충전하거나 줄이지 말고 Retry-After(5초)만큼 기다렸다 같은 요청을 그대로 보내요(요금은 안 붙었어요). Idempotency-Key 를 실었으면 같은 키 · 같은 본문으로 보내요 — 새 요청 ID 로 다시 접수돼요(드물게 접수 기록을 못 적으면 x-should-retry: false 와 조회 주소가 붙어 와요 — 그땐 다시 보내지 말고 그 주소를 GET 해요). 둘은 막은 자리만 달라요 — 402 는 같은 지갑의 다른 호출(다른 키 것도)이 잡아 둔 몫 때문에 지갑이 모자란 거고, 429 는 같은 키로 보낸 다른 호출이 잡아 둔 몫(GET /v1/key 의 month.held_credits)까지 더하면 이 키의 이번 달 한도를 넘는 거예요(2026-10-30 부터). 429 엔 x-should-retry: true 가 붙어서 SDK 재시도를 켜 두셨으면 SDK 가 Retry-After 만큼 기다렸다 스스로 다시 보내요 — 다만 기본 두 번까지라, 그 뒤 올라온 429 도 코드가 계속 기다려요. 402 는 SDK 가 안 보내니 코드가 보내요(SDK 동작). 앞 호출이 끝날 때까지 길게는 몇 분 걸려요 — 「402 는 호출 전에 나요」 둘째 항목과 같아요(아래 감싸개 call() 이 둘 다 기다려요). 다시 보낸 뒤 reason 이 바뀌면 그 호출이 몫을 거의 다 쓰고 정산된 거예요 — 429 key_month_limit 이면 기다려도 안 풀리니 max_tokens 를 줄이거나 한도를 올리거나 month.resets_at 까지, 402 hold_exceeds_balance 면 줄이거나 충전해요. 그림 · 소리 문의 402 엔 Retry-After 가 없으니(429 엔 있어요) 몇 초 쉬고 그대로 보내요.

실행 여부와 정산을 나눠 확인하세요#

글 문은 모델 회사로 보내기 전 거절과 보낸 뒤 실행 불명을 구분해요. 422 upstream_execution_unconfirmed 는 실행되지 않았다는 뜻이 아니에요 — 이 응답엔 요금이 안 붙지만 모델 회사에서 실행됐을 수 있어요. 상태 조회가 제공되면 result 와 settlement 를 따로 확인하세요 — 받은 x-gateway-status-url 을 같은 API 키로 GET 해요(요금 없음). 답 본문은 돌려주지 않아요 — result.state 가 completed 여도 글은 다시 못 받아요(응답 모양은 아래 「Idempotency-Key 를 실었을 때」 · https://oneport.kr/docs/reference/requests.md). finish_reason 이 length 로 잘린 2xx 답과 도중에 끊긴 스트림은 쓴 몫이 있어요. 잠시 뒤 그대로 다시 보낼 수 있는 글 문의 실패에는 Retry-After(초)가 와요 — 402 · 429 의 error.reason held_by_others 는 5초, 503 api_error 는 2초, 실행 전 거절이 확인된 429 rate_limit_error 는 벤더 값(1~60초 · 없으면 5초)이에요. Claude 과부하 529 는 벤더가 값을 알려 줬을 때만 그 값(1~60초)이 붙어요. 토큰 세기 문(/v1/messages/count_tokens)도 503 api_error 에 2초, 429 rate_limit_error 에 벤더 값(1~60초 · 없으면 5초)을 실어요. x-should-retry: true 는 429 key_limit_exceeded 의 error.reason held_by_others 에만 와요 — 그 밖엔 이 머리글이 없거나 false 예요. 먼저 x-should-retry: false 인지 보세요. 이 값이 있으면 그대로 다시 보내지 않으며(뜻은 위 「다시 보내나」 문단) Retry-After 도 없어요(504 error.reason "timeout" 만 잠시 뒤 한 번 직접 다시 보내도 돼요). 그 밖에 Retry-After 가 있으면 그만큼 기다리세요. Retry-After 가 없는 402 는 충전하거나 max_tokens · 한도를 고쳐요. 그림 · 소리 · 임베딩 · 검열의 실패는 각 레퍼런스의 별도 규칙을 따르세요. 아래는 글 문의 응답 유실과 스트림 정산 규칙이에요.

  • 스트림이 200 으로 시작한 뒤 끊기거나 error 조각이 오면 — 그때까지 쓴 토큰만큼 크레딧을 이미 사용했어요. Claude 는 입력 · 캐시를 시작 때 센 대로 세고, 출력은 끝의 누적 출력 수(message_delta 의 usage)를 받기 전에 끊기면 흘려보낸 글 · 도구 인자 · 생각 글 바이트 ÷ 3 토큰과 Claude 가 그때까지 알려 준 수 가운데 큰 쪽으로 세요(미리 잡아 둔 몫을 넘지 않아요 · 2026-10-31 부터 — 예전엔 Claude 가 알려 준 수만 셌어요). 토큰 수가 끝 조각(usage) · 끝 이벤트에만 오는 모델(Claude 밖의 모델 · /v1/responses)은 그 전에 끊기면 저희가 흘려보낸 글을 출력으로 어림해 사용해요 — /v1/chat/completions 면 delta.content · delta.refusal · 생각 글(delta.reasoning_content · delta.reasoning 중 긴 쪽 하나) · 도구 인자(delta.tool_calls[].function.arguments · 옛 delta.function_call.arguments), /v1/responses 면 이름이 .delta 로 끝나는 이벤트의 delta 글 전부예요(글 · 도구 인자 · 생각 요약 · 거절 글 등 — 소리 조각만 빼요). 그 글 바이트를 다 더한 뒤 3 으로 나눠 한 번 올려요 — 손님 쪽에서 센 값은 저희 어림과 두 방향으로 달라요: 끊기기 직전 조각이 손님께 못 닿았으면 손님 값이 작고, 어림이 예약 금액에서 잘리면 저희 값이 작아요. 이 출력 어림에서는 입력을 세지 않아요. 손님께 글이 안 보였다는 사실만으로 실행 여부나 요금 여부를 판단하지 마세요. 어림은 이 호출에 미리 잡아 둔 예약 금액(402 를 가르는 그 예약 — 보통 보낸 몸통(저희가 받은 JSON 을 공백 없이 다시 쓴 UTF-8 바이트 — 한글 한 글자는 3바이트) 3바이트를 1토큰으로 센 입력 × 입력 단가 + max_tokens(/v1/responses 는 max_output_tokens · 안 적으면 8,192) × 출력 단가 · 가장 작아도 약 0.4 크레딧 · 구간 단가 · 캐시 쓰기 단가로 잡는 모델 같은 예외는 「남은 한도」 장의 최대 몫)을 넘지 않아요. 입력은 0 으로 두고 예약 금액 전부(입력 몫까지)를 출력으로 쓸 수 있게 세서, 어림 토큰이 max_tokens 보다 많을 수 있어요. 다시 보내면 새 호출이라 또 사용해요. Claude 인지는 GET /v1/models 의 owned_by 가 anthropic 인지로 보세요 — Claude 는 받은 글로 어림하지 않고 벤더가 흐름 안에 보낸 토큰 수로만 세요 — 스트림이 시작될 때(message_start) 벤더가 센 입력 토큰(캐시 읽기 · 쓰기 포함)을 그대로 사용해서, 끝 무렵 이벤트(message_delta) 전에 끊기면 입력 전부와 시작 이벤트(message_start)에 벤더가 적은 출력 토큰 수 그대로를 사용해요. /v1/chat/completions 로 받으면 이 수는 끝 usage 조각에 실리고, 답 도중 실패하면(벤더 error · 저희 시간 제한 · 연결 끊김) error 조각 바로 앞의 usage 조각(choices 가 빈 배열)에 그때까지의 수가 실려요 — 시작 이벤트 전에 실패했거나 손님 쪽에서 먼저 끊은 흐름에서만 못 봐요. 글 모델의 pricing 엔 rates 배열과 input_credits_per_mtok · output_credits_per_mtok 가 같이 오고, 두 칸은 rates 의 input_text · output 줄과 같은 값이에요. 크레딧으로 얼마인지는 GET /v1/models 의 모델마다 pricing.output_credits_per_mtok(100만 토큰당 크레딧 · 입력은 input_credits_per_mtok)로 셈해요 — 어림 토큰 × 그 값 ÷ 1,000,000 이에요. GET /v1/models 는 {"object": "list", "data": [ … ]} 모양이고, pricing.rates 는 객체가 아니라 {dimension, unit, unit_label, credits} 줄의 배열이에요(글 모델의 dimension 은 input_text · output · cache_read · cache_write 이고 unit 은 mtok). 끝까지 받은 답(과 위처럼 usage 조각이 온 잘린 답)은 끝 usage 의 cost_credits 가 그 호출에 쓴 값이에요 — 정산이 2초 안에 안 끝나 그 칸이 없으면 usage 로 셈해요 — prompt_tokens 안에 캐시 읽기(prompt_tokens_details.cached_tokens)와 캐시 쓰기(prompt_tokens_details.cache_write_tokens · 캐시 쓰기가 있을 때만 와요)가 들어 있어서 그 둘은 빼고 cache_read · cache_write 단가로 세고, 출력은 total_tokens − prompt_tokens 로 세요(Gemini 는 생각한 몫이 completion_tokens 에 안 들어가요). 입력(캐시 읽기 · 쓰기 포함)이 pricing.tier.above_input_tokens 이상인 요청은 그 요청 전체를 pricing.tier 의 input_credits_per_mtok · output_credits_per_mtok 로 세요(tier 가 없는 모델은 구간이 없어요) — 셈 전체는 「모델과 단가」 장이에요.
  • 422 upstream_execution_unconfirmed — 실행 결과를 확인하지 못했어요. 고객 정산이 not_charged 로 확인돼도 모델 회사에서 실행되지 않았다는 뜻은 아니에요. 같은 일이 두 번 돌 수 있으니 자동으로 다시 보내지 마세요.
  • 손님 쪽에서 먼저 연결을 끊으면 — 저희도 벤더 호출을 끊어요. 스트림은 벤더 답이 시작되는 즉시 200 머리말을 보내서, 서버가 벤더 응답을 받기 전에 취소가 확정되면 요금이 안 붙어요. 손님 쪽에서 머리말을 못 받았다는 사실만으로 취소나 미실행이 확정되지는 않아요. 다만 스트림이어도 손님이 끊은 게 아니라 연결 오류로 머리말을 못 받았으면, 저희가 이미 흘려보내기 시작했는지 손님 쪽에선 알 수 없어요 — Claude 는 흐름이 시작될 때 입력 전부를 사용하니 「사용됐는지 모름」으로 두세요. Claude 밖 모델의 출력 어림도 저희가 벤더에서 받은 조각을 기준으로 해요 — 손님께 못 닿은 조각도 들어가므로 화면에 글이 없다는 이유로 0원이라고 판단하지 마세요. 그래서 머리말을 못 받고 연결 오류로 끝났으면 Claude 밖 모델도 「사용됐는지 모름」으로 두세요. 머리말 뒤에 끊으면 그때까지 쓴 토큰만큼 사용해요(끝 조각 전이면 위처럼 어림해요 — 마지막 글 조각까지 받고 끊어도 마찬가지예요). 스트림이 아닌 요청도 답을 못 받았다는 이유만으로 무료나 미실행으로 판단하지 마세요. 모델 회사로 보낸 뒤 본문을 확인하지 못했으면 실행 불명이며, 다 받은 뒤 전달 중에 끊긴 경우에도 이미 사용했을 수 있어요. 시간 제한이 아니라 연결 오류로 응답을 못 받았을 때도 같아요 — 스트림이 아니어도 저희가 벤더 답을 다 받은 뒤였으면 이미 사용됐으니, 그대로 다시 보내면 두 번 사용할 수 있어요. 손님 쪽에서는 둘 중 어느 쪽인지 알 수 없어요 — 스트림이 아닌 호출이 연결 오류 · 시간 초과로 끝났으면 「사용됐는지 모름」으로 두세요. Idempotency-Key 로 접수해 x-gateway-status-url 을 받은 요청은 그 주소를 GET 조회해 결과와 정산을 확인하세요. 일반 요청 ID에는 이 조회가 제공되지 않아요. 다만 연결 자체를 못 맺은 실패(이름 찾기 · TCP · TLS 단계 — Python openai SDK 면 APIConnectionError 의 __cause__ 가 httpx.ConnectError · ConnectTimeout · PoolTimeout 이에요, SDK 동작)는 요청이 저희에게 안 닿은 거라 다시 보내도 두 번 사용하지 않아요. 「사용됐는지 모름」은 연결이 된 뒤 응답을 못 받은 경우예요.

Idempotency-Key 를 실었을 때#

Idempotency-Key 를 실은 글 문 요청도 접수된 뒤 실행 전에 막힌 실패는 키 없는 호출과 같은 머리글로 와요 — 접수가 풀려요. x-should-retry: false 없이 온 402 · 429 의 held_by_others · 429 rate_limit_error · 503 api_error · 529 · 그 밖의 5xx upstream_error 는 Retry-After 만큼 기다렸다 같은 키 · 같은 본문으로 다시 보내요(529 · 5xx upstream_error 는 Retry-After 가 없을 수 있어요 — 그땐 간격을 직접 정해요). 새 요청 ID 로 다시 접수돼 실행되고, 앞 요청은 실행되지 않았으니 두 번 실행되지 않아요. 처음 응답의 조회 주소는 남아서 execution not_started · result.state failed · settlement.state not_charged 로 보여요. 400 · 403 · 404 와 402 hold_exceeds_balance · below_minimum_balance 는 x-should-retry: false · Retry-After 가 없어도 그대로 다시 보내면 같은 실패예요. 이렇게 고쳐 보내는 실패(429 key_month_limit 포함)는 고친 요청을 새 키로 보내요(같은 키로 본문을 바꾸면 409 idempotency_conflict 예요). 충전하거나 한도가 다시 열린 뒤 같은 요청을 보낼 땐 같은 키를 그대로 써도 돼요. x-should-retry: false 가 붙은 실패는 같은 요청을 자동으로 다시 보내지 마세요. 422 upstream_execution_unconfirmed 는 받은 x-gateway-status-url 을 GET 해 결과와 정산을 확인해요. 그 밖에 x-should-retry: false 와 조회 주소가 같이 온 실패(503 api_error · 5xx upstream_error 등 — 접수가 풀렸는지 저희가 확인하지 못한 것)도 조회 주소를 GET 해서 execution 이 not_started 면 같은 키 · 같은 본문으로 다시 보내요(새로 접수돼요) — started · unknown 이면 사람이 정해요. held_by_others 밖의 키 · 그룹 한도 429 는 원래 이 머리글로 와요 — 조회가 not_started 여도 그대로 보내면 같은 429 라 위 갈래대로 해요. 모델 회사가 거절한 4xx upstream_error 는 키를 실으면 x-should-retry: false 가 붙고 같은 키는 409 예요 — 문장대로 고친 요청을 새 키로 보내요. 예외는 둘이에요. 504 error.reason "timeout" 은 모델 회사가 실행하기 전에 저희 처리 기한(4분)이 끝난 거라(요금 없음) 잠시 뒤 한 번 같은 키 · 같은 본문으로 다시 보내도 돼요 — x-should-retry: false 는 그대로 붙고 Retry-After 는 없으니 간격은 직접 정해요. 모델 회사로 보낸 뒤 첫 응답을 120초 안에 못 받은 건 504 가 아니라 422 upstream_execution_unconfirmed 예요. 조회 주소와 같이 온 503 request_state_unavailable · request_store_unavailable 도 코드가 같은 키 · 같은 본문으로 다시 보내도 돼요(아래 503 문단). 조회 주소(x-gateway-status-url · Location) 없이 온 503 api_error(API 키를 잠깐 못 읽은 것 · 「지금 이 키를 확인하지 못했어요」)와 503 request_state_unavailable · request_store_unavailable 은 새 Idempotency-Key 로 바꾸지 말고 잠시 뒤 같은 Idempotency-Key · 같은 본문으로 다시 보내요 — 끊긴 뒤 다시 보낸 전송이었다면 앞 요청이 접수됐는지 이 응답으로는 몰라서, 바꾸면 두 번 실행될 수 있어요. 이 셋엔 Retry-After: 2 가 오고 x-should-retry 는 없어요. 같은 키 · 같은 본문에 409 request_already_exists 가 오면 그 접수는 다시 받지 않는 거예요(처리 중 · 끝남 · 실행 여부 모름). 새 키로 바꾸지 말고 그 409 의 x-gateway-status-url 을 GET 해요(읽는 법은 아래 execution 문단). 키를 안 실은 호출은 예전 그대로예요.

키는 공백 · 제어문자 없는 ASCII(영문 · 숫자 · 기호) 8~200자예요(어기면 400). 같은 API 키 안에서만 같은 요청으로 봐요. 한 번 쓴 키는 지워지지 않으니 새 요청마다 새 값을 써요. 같은 키 · 같은 본문을 동시에 두 번 보내도 하나만 접수돼요 — 다른 하나는 409 request_already_exists 와 먼저 접수된 요청의 조회 주소를 받아요. 같은 키로 본문(칸 순서나 JSON 사이 공백은 상관없어요) · 주소 · anthropic-version · anthropic-beta · openai-beta 머리글을 바꾸면 409 idempotency_conflict 예요 — 조회 주소 없이 와요. 409 request_already_exists 몸통에는 답이 없어요. 조회 주소로는 실행 · 결과 · 정산 상태만 보고, 답 본문은 다시 못 받아요(response_stored: false).

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} 예요. settlement.state 가 unknown 이면 cost_credits 는 null 이에요 — 0 으로 읽지 말고 접수 뒤 약 14분 안이면 다시 조회해요(지나도 그대로면 문의). 칸마다 값(result.state · settlement.state 의 값 목록 · created_at 시각 꼴)은 https://oneport.kr/docs/reference/requests.md 에 있어요.

execution 은 claimed(접수만) · started(모델 회사로 보냄) · not_started(실행 전에 막힘) · unknown(보냈는지 모름 — 보내기 시작한 뒤 결과를 못 적은 것) 이에요. not_started 는 모델 회사로 안 보냈거나, 보낸 시도가 전부 실행 전 거절로 확인된 거예요 — 보내기 전에 저희 쪽에서 실패한 접수도 이렇게 적혀요(2026-10-29 부터). 이때 result.state 는 failed, settlement.state 는 not_charged(cost_credits 0)이고, 같은 키 · 같은 본문으로 다시 보내면 새 요청 ID 로 다시 접수돼요. 글 문은 접수 뒤 약 14분 안에 끝나서, 접수 뒤 약 14분이 지나도 claimed 면 모델 회사로 보내지 않은 채 멈춘 접수예요. 접수 뒤 15분(900초)이 지나면 조회가 execution not_started · result.state failed · settlement.state not_charged 로 바뀌고, 같은 키 · 같은 본문으로 다시 보내면 새로 접수돼 실행돼요. 그 전에 같은 키로 보내면 409 request_already_exists 예요 — 새 키로 바꾸지 말고 15분이 지난 뒤 같은 키로 보내요. started 는 보냈다는 뜻일 뿐이에요. 2026-10-29 전에 접수된 요청은 보낸 뒤 실행 전에 막힌 것도 started 로 남아 있어요 — http_status 가 402 · 429 · 503 · 504 · 529 면 모델 회사가 실행하지 않은 거예요. 그 뒤에 접수된 요청은 not_started 로 적혀서 이 조합이 새로 생기지 않아요(created_at 날짜로 가르지 말고 이 조합으로 봐요). 같은 키는 409 라서 다시 받으려면 새 키로 보내요 — 앞 요청이 실행되지 않았으니 새 키여도 두 번 실행되는 게 아니에요. started 인데 result.state 가 unknown 이면 아직 답이 오는 중일 수 있어요(사용 기록은 답이 끝난 뒤에 적혀요) — 접수 뒤 약 14분이 지나도 그대로거나 execution 이 unknown 이면 실행됐을 수 있어 사람이 정해요.

Idempotency-Key 를 실었으면 200 머리말을 받기 전의 연결 오류 · 시간 초과 뒤에 같은 Idempotency-Key · 같은 본문으로 다시 보내세요(몇 번 보내도 두 번 실행되지 않지만, 간격은 늘려 가며). 200 을 받은 뒤 끊긴 스트림은 잘린 답이라 같은 Idempotency-Key 는 409 예요 — 받은 글로 이어 받아요(이어 받는 요청은 본문이 달라 새 Idempotency-Key). 앞 요청이 접수됐으면 새로 실행하지 않고 409 request_already_exists 와 조회 주소(x-gateway-status-url · Location · error.status_url)가 와요 — 그 409 의 request-id 가 앞 요청의 요청 ID 라 문의엔 그 값을 써요. 모델 회사로 보낸 뒤 끊긴 앞 요청은 저희도 멈춰서 조회하면 대개 execution unknown 이라, 다시 만들지는 사람이 정해요. 앞 요청이 접수 전에 끊겼거나 실행 전에 막혀 풀렸으면 그때 새로 접수돼 실행돼요 — 모델 회사로 보내기 전에 멈춘 접수도 풀려요(늦어도 접수 뒤 15분). 그 전송이 조회 주소(x-gateway-status-url · Location) 없이 실패하면 접수 전에 막힌 거라 앞 요청이 접수됐는지 아직 몰라요 — 새 Idempotency-Key 로 바꾸지 말고, 503 이면 잠시 뒤 같은 Idempotency-Key · 같은 본문으로 다시 보내요. 키는 API 키를 확인한 바로 다음, 잔액 · 한도 검사보다 먼저 접수해요. 그래서 그 전송이 409 가 아닌 응답(200 · 402 · 429 처럼)과 x-gateway-status-url 을 받으면 그 전송이 새로 접수된 거예요 — 앞 요청은 접수되지 않았거나 실행 전에 막혀 풀린 거라 실행되지 않았어요. 조회 주소 없이 오는 401 · 400 · 413 · 503 api_error(「지금 이 키를 확인하지 못했어요」) · 503 request_state_unavailable · request_store_unavailable 은 접수 전에 막힌 거라 앞 요청 얘기를 해 주지 않아요.

503 request_state_unavailable · request_store_unavailable 은 Idempotency-Key 접수 기록을 잠깐 못 읽거나 못 쓴 거예요. 조회 주소가 같이 왔으면 접수된 뒤라 x-should-retry: false 가 붙고 Retry-After 가 없어요(SDK 는 다시 보내지 않아요) — 그 주소를 GET 하거나, 코드가 몇 초 뒤 한 번 같은 Idempotency-Key · 같은 본문으로 다시 보내요(이미 접수돼 있으면 409 와 조회 주소가 와요). 조회 주소 없이 왔으면 접수 전에 실패한 거예요 — 문장은 「요청 상태를 확인하지 못했어요. 같은 Idempotency-Key를 유지해 주세요.」예요. 같은 Idempotency-Key · 같은 본문으로 다시 보내면 그사이 접수가 됐을 땐 409 와 조회 주소가, 안 됐을 땐 새 접수가 돼요. 상태 조회 GET 에서 났으면 Retry-After(2초) 뒤 같은 주소를 다시 GET 해요. 접수하는 사이 API 키가 꺼졌거나 기한이 끝났거나 지갑이 멈췄으면 키 확인 단계와 같은 401 authentication_error 로 와요 — error.reason 이 이유를 말하고(「인증」 장 「키가 안 열릴 때」 표), 조회 주소가 없고 접수도 안 된 거예요(API 키를 잠깐 못 읽었으면 503 api_error 「지금 이 키를 확인하지 못했어요」예요).

커넥터 부탁 문(POST /v1/connectors/requests)은 Idempotency-Key 가 꼭 있어야 해요(없거나 꼴이 틀리면 400) — 글 문의 409 request_already_exists 와 조회 주소(/v1/requests/<id>)는 이 문엔 없어요. 새 부탁이면 201, 이미 있던 줄이면 200 으로 부탁 한 줄이 오고, 결과는 그 줄의 state 칸(received · reviewing · approved · declined · blocked)으로 봐요. 같은 API 키로 같은 값 · 같은 본문을 다시 보내면 새 줄 없이 그 부탁을 200 으로 돌려줘요 — 그사이 결과가 나왔어도(approved · declined · blocked) 그 줄이 와요(Location 은 /v1/connectors/requests/{id}). 그 줄이 declined 이고 can_request_again 이 true 면 고쳐서 새 값으로 다시 부탁해요 — 같은 값이면 그 거절 줄이 또 와요. 받은 값은 기한 없이 기억해요 — 지난 부탁에 쓴 값을 새 부탁에 다시 쓰면 새 줄이 아니라 그 옛 줄(200)이나 409 가 와요. 같은 값으로 본문을 바꾸면 409 idempotency_conflict 예요 — 그 값으로 먼저 보낸 부탁은 이미 접수돼 있어요. x-should-retry: false 가 붙어서 SDK 가 스스로 다시 보내지 않아요(이 문엔 SDK 함수가 없어서, SDK 의 저수준 호출로 부를 때 얘기예요). 400 · 401 · 403 · 413 · 429 거절은 그 값에 남지 않아서 고친 요청에 같은 값을 써도 돼요. 503 api_error 를 받았거나 응답을 못 받았으면 같은 값 · 같은 본문으로 다시 보내요 — 저희가 이미 받은 부탁이면 새 줄 없이 그 줄이 200 으로 와요. 본문은 service_name(1~100자 · 꼭 있어야 해요)과 reason(500자까지 · 빼거나 null 이어도 돼요) 두 칸이고, 다른 칸이 있으면 400 이에요. Idempotency-Key 는 공백 · 제어문자 없는 ASCII(영문 · 숫자 · 기호) 8~200자예요. 같은 지갑에서 같은 서비스를 부탁해 결과를 기다리는(received · reviewing) 줄이 있으면, 다른 API 키나 새 값으로 보내도 새 줄 없이 그 줄이 200 으로 와요 — 열린 부탁이 상한에 닿았어도 429 too_many_open 이 아니에요. 이 문은 요금이 안 붙고 크레딧 · 키 한도 · 강좌 몫을 보지 않아서 402 와 429 key_limit_exceeded · group_limit_exceeded 는 오지 않아요. 이 문이 내는 413 은 JSON 본문이 8,000바이트를 넘은 거예요 — 다른 오류처럼 JSON 몸통에 request_id 가 와요(4.5MB 를 넘으면 앞단의 영어 413 이에요). 자세한 건 「커넥터」 장(https://oneport.kr/docs/reference/connectors.md)이에요.

폴백 — 실행 전 거절이 확인됐을 때만 다른 경로로#

글 문과 채팅은 실행 전 거절로 확인된 429 · 저희 쪽 사정으로 실행 전에 거절된 경우 · 완전한 본문의 Anthropic overloaded_error(5xx)에서만 같은 모델의 다음 경로로 넘어가요. Anthropic 과부하는 상태 529만으로 인정하지 않아요 — 응답 본문을 끝까지 읽어 overloaded_error 를 확인해야 해요. 그 거절만 남으면 원래 5xx upstream_error 로 돌아올 수 있어요. 저희 쪽 사정의 실행 전 거절만 확인된 채 경로가 다 떨어지면 503 api_error · error.reason provider_unavailable 로 와요. 실행 불명이 한 번이라도 있으면 이 재시도 가능한 503 으로 바꾸지 않아요. 일반 400 · 404 거절은 요청을 고쳐야 하므로 그대로 돌려드려요. 모델 회사로 보낸 뒤 연결 실패 · 시간 초과 · 408 · 실행 전 거절이 확인되지 않은 5xx, 성공 머리글을 받은 뒤 JSON 을 읽지 못한 경우는 실행 불명으로 멈춰요. 공개 글 문에서는 422 upstream_execution_unconfirmed · x-should-retry: false 로 알리고 Retry-After 를 보내지 않아요. 모델 회사에서 이미 실행됐을 수 있어 다른 경로로 넘기거나 같은 요청을 자동으로 다시 보내지 않아요. 응답 헤더 x-gateway-fallback-depth 는 0 부터 세요 — 0 이면 첫 경로에서 됐고, 1 이상이면 그만큼 다른 경로로 돌았어요. 벤더까지 간 실패 응답에도 붙어요 — 400 · 401 · 402 · 403 · 404 · 키 한도 429 처럼 부르기 전에 막힌 응답엔 없어요. 스트림이 200 으로 시작했을 때도 머리글에 붙어요(Python openai SDK 는 stream.response.headers 로 읽어요 — SDK 동작). /v1/chat/completions 가 빼거나 옮긴 칸은 x-gateway-ignored-params · x-gateway-mapped-params 에 같이 와요.

코드 없이 부를 때 — n8n 같은 도구#

n8n · 구글 시트처럼 응답을 꺼내 쓰는 도구에서도 문장 말고 몸통의 error.type(OpenAI 형식은 error.code 도 같은 값) · error.reason 과 머리글 retry-after · x-should-retry 로 가르세요 — 429 rate_limit_error 와 5xx upstream_error 는 모델 회사가 준 문장이 그대로 와서 글자로는 못 갈라요(402 는 문장으로도 갈려요 — 위 「402 는 호출 전에 나요」). 흐름에선 이렇게 옮겨요 — 기다렸다(402 · 429 의 held_by_others · 429 rate_limit_error · 503 api_error)는 Retry-After 만큼 쉬고 그대로 · 고쳐서(hold_exceeds_balance · key_month_limit · group_budget)는 max_tokens 를 줄여 다시 · below_minimum_balance 는 충전 알림 · 그 밖(key_day_limit · 강좌 닫힘 · 422 · 모르는 값)은 사람에게요. n8n HTTP Request 노드면 Options 의 Include Response Headers and Status 와 Never Error 를 켜야 4xx · 5xx 에도 상태 · 머리글 · 몸통을 받아요. 이렇게 Never Error 를 켠 노드에선 Retry On Fail 은 꺼 두세요 — 4xx · 5xx 는 오류가 아니게 되어 연결 오류 · 시간 초과에만 다시 보내니, 이미 실행된 요청이 두 번 사용될 수 있어요. Retry-After 는 정수 초라 Wait 노드(After Time Interval)의 Amount 에 초로 그대로 넣고, 노드 Timeout 은 300000(ms)으로 두세요(n8n 동작). Make 「HTTP」의 Make a request 는 고급 설정의 「Return error if HTTP request fails」를 No 로 둬야 4xx · 5xx 에도 시나리오가 멈추지 않고 상태 코드 · 몸통을 다음 단계(시트 쓰기 등)로 넘겨요(10월 기준 · 도구 동작). 저희 오류 몸통은 JSON 이라(호스팅이 끊은 413 만 글자예요) error.type · error.reason(없는 갈래도 있어요) · error.message · error.request_id 를 그대로 옮겨 적으면 돼요 — 응답 없이 끊긴 실패엔 요청 ID 가 없어요.

그대로 쓰는 감싸개 — Python · TypeScript#

위 표와 문단을 코드로 옮긴 감싸개예요(/v1/chat/completions · openai SDK). 잠시 뒤 다시 보낼 갈래만 스스로 다시 보내고(Retry-After 가 오면 그만큼 기다려요), 나머지는 OnePortError 의 action 과 request_id(문의할 때 쓰는 요청 ID)로 다음 할 일을 알려 드려요. 스트림 함수는 잘린 답인지(cut)와, usage 를 못 받고 끊겼을 때 저희가 사용으로 어림하는 값(estimate)을 같이 돌려줘요.

이 감싸개는 Idempotency-Key 를 싣지 않지만, 실어도 그대로 돌아요. 실행 전에 막힌 402 · 429 의 held_by_others · 429 rate_limit_error · 503 api_error · 529 는 키를 실어도 x-should-retry: false 없이 와서(Retry-After 도 와요 — 529 는 Anthropic 이 값을 줬을 때만) classify() 가 retry_later 로 가르고, call() 이 같은 키 · 같은 본문으로 다시 보내면 새 요청 ID 로 다시 접수돼요. 키를 쓰시려면 요청 하나에 키 하나를 만들고, 다시 보낼 때도 같은 키를 실어요. Python 은 call(..., extra_headers={"Idempotency-Key": key}) 로 넘기면 call() 이 같은 params 로 다시 보내요. TypeScript 는 머리글을 create 의 둘째 인자로만 받아서(SDK 동작) call() 의 넷째 인자 headers 로 넘기면 client.chat.completions.create(params, { headers }) 로 실어요 — call(params, 3, 800_000, { "Idempotency-Key": key }) 처럼 다시 보낼 때도 같은 객체를 넘겨요. classify() 가 contact 로 올리는 것 중 키 갈래가 있어요 — 422 · request_already_exists 는 받은 x-gateway-status-url 을 GET 해요. request_state_unavailable · request_store_unavailable 과 504 error.reason "timeout" 은 잠시 뒤 같은 키 · 같은 본문으로 한 번 다시 보내요 — 키를 실으면 call() 이 classify() 보다 먼저 retry_same_key() · retrySameKey() 로 이 갈래를 가려, retries 와 따로 한 번만 스스로 다시 보내요(또 실패하면 OnePortError 로 올라와요). OnePortError 엔 원래 오류가 실려요 — Python 은 e.__cause__, TypeScript 는 err.cause 예요. 422 · 409 의 x-gateway-status-url 은 그 원래 오류의 머리글(Python e.__cause__.response.headers · TypeScript (err.cause as APIError).headers)에서 읽어요. 모델 회사가 거절한 4xx upstream_error 는 키를 실으면 x-should-retry: false 가 붙어 contact 로 와요 — 문장대로 고쳐요. 그 밖에 x-should-retry: false 와 조회 주소가 같이 와 contact 로 오른 실패는 위 「Idempotency-Key 를 실었을 때」대로 조회해요. 고쳐 보내는 갈래(fix_request · lower_max_tokens · shrink_input · use_stream)와 이 4xx 는 고친 요청을 새 키로 보내요. 연결이 끊긴 뒤 같은 키로 다시 보내는 일은 이 감싸개 밖이에요(위 「Idempotency-Key 를 실었을 때」).

Python — openai SDK
# pip install openai — 원포트 오류 처리 감싸개(Python). 갈래는 위 오류 표와 같아요.
import json, math, os, random, time, urllib.request
import openai

BASE = "https://oneport.kr"
KEY = os.environ["ONEPORT_API_KEY"]
# SDK 자체 재시도는 꺼요(연결 오류 · 시간 초과도 다시 보내 두 번 사용될 수 있어요) — 상태 코드로 온 실패만 아래 call() 이 다시 보내요.
client = openai.OpenAI(base_url=f"{BASE}/v1", api_key=KEY, timeout=300, max_retries=0)

class OnePortError(Exception):
    # action: retry_later · fix_request · fix_key · top_up · lower_max_tokens · shrink_input · use_stream · day_limit · month_limit · group_limit · use_light_model · ask_space_admin · contact
    def __init__(self, action, status, type_, message, request_id=None):
        super().__init__(f"[{action}] {status} {type_}: {message}")
        self.action, self.status, self.type, self.message, self.request_id = action, status, type_, message, request_id

def classify(e: openai.APIStatusError) -> str:
    body = e.body if isinstance(e.body, dict) else {}  # Python SDK 는 error 안쪽만 줘요 — {"type", "message", "code"}
    t, msg, code, status = body.get("type") or e.type, body.get("message") or "", body.get("code"), e.status_code
    no_retry = e.response.headers.get("x-should-retry") == "false"
    if t in ("upstream_execution_unconfirmed", "request_already_exists", "request_state_unavailable", "request_store_unavailable"):
        return "contact"  # 422 · 409 는 받은 상태 주소를 GET 조회(없으면 요청 ID와 시각으로 문의) · 503 두 type 은 같은 키로 한 번 직접(위 문단)
    if t == "insufficient_credit":
        # 기계가 읽는 칸(reason)을 먼저 보고, 없으면 문장으로 가려요.
        reason = body.get("reason")
        if reason == "held_by_others" or "다른 호출이 잡아 둔 몫" in msg:
            return "contact" if no_retry else "retry_later"  # 키를 실어도 이 402 엔 대개 x-should-retry: false 가 없어요(접수 기록을 못 적었을 때만 붙어요) — 붙어 왔으면 자동으로 다시 보내지 말고 받은 조회 주소를 GET 해요
        if reason == "hold_exceeds_balance" and not msg.startswith("이 요청에 필요한"):
            return "shrink_input"  # 임베딩 · 그림 · 소리 문 — 이 요청 몫이 잔액보다 커요. 문장이 말한 것(묶음 · 참고 그림 · 글 · 파일 길이)을 줄여 보내요
        if not msg.startswith("이 요청에 필요한"):
            return "top_up"  # 잔액이 최소치보다 적어요 — https://oneport.kr/buy
        if "stream: true 로 보내거나" in msg:
            return "use_stream"
        # 몫 대부분이 입력이면 max_tokens 를 줄여도 거의 안 줄어요 — 첨부 · 대화 기록을 줄이거나 나눠 보내요.
        return "shrink_input" if "미리 잡는 몫 대부분이 입력" in msg else "lower_max_tokens"
    if t == "key_limit_exceeded":
        # 오늘 한도: 쓴 몫만 봐서 max_tokens 를 줄여도 같아요 → day.resets_at 까지 기다려요.
        # key_month_limit: 쓴 몫과 이 요청 최대 몫만으로 이번 달 한도를 넘었어요 — max_tokens 를 줄이면 될 수 있어요 → 아니면 month.resets_at.
        # held_by_others: 같은 키로 아직 끝나지 않은 호출 몫까지 더하면 넘어요 — 그 호출이 끝나면 풀려서 call() 이 기다렸다 그대로 다시 보내요.
        # 모든 문이 reason(key_day_limit · key_month_limit · held_by_others)으로 와요 — 없으면(작업 문을 다시 조회한 응답) 문장으로 갈라요.
        reason = body.get("reason")
        if reason == "held_by_others":
            return "contact" if no_retry else "retry_later"  # 이 429 엔 x-should-retry: true 가 붙어요 — false 로 왔으면 접수 기록을 못 적은 것이라 받은 조회 주소를 GET 해요
        if reason == "key_day_limit" or (reason is None and "오늘" in msg):
            return "day_limit"
        # 이번 달 한도도 몫 대부분이 입력이면 max_tokens 를 줄여도 거의 안 줄어요 — 첨부 · 대화 기록을 줄이거나 나눠 보내요.
        return "shrink_input" if "미리 잡는 몫 대부분이 입력" in msg else "month_limit"
    if t == "group_limit_exceeded":
        # 갈래는 error.reason(위 표) — group_budget 은 남은 몫이 있으면 상한을 줄여서, group_tail 은 단가가 낮은 모델로.
        reason = body.get("reason")
        if reason in ("group_closed", "group_not_started", "group_ended"):
            return "ask_space_admin"
        if reason == "group_tail":
            return "use_light_model"
        # 모르는 reason 이 오면 아래 문장 낱말로 갈라요.
        if reason != "group_budget" and ("그룹이 닫혀" in msg or "부터 쓸 수 있어요" in msg or ("기간이" in msg and "끝났어요" in msg)):
            return "ask_space_admin"
        # 몫 대부분이 입력이면 출력 상한을 줄여도 거의 안 줄어요 — 첨부 · 대화 기록을 줄이거나 나눠 보내요.
        return "shrink_input" if "미리 잡는 몫 대부분이 입력" in msg else "group_limit"
    if t == "group_member_limit_exceeded":
        return "ask_space_admin"  # 웹 채팅의 1인 몫이라 API 키엔 안 와요
    if t == "authentication_error":
        # 갈래는 reason 으로(「인증」 장 표) — 지갑이 멈췄으면(account_inactive) 키를 고칠 일이 아니에요.
        # reason 이 없으면(관리 키 문 /v1/keys) 키를 고칠 갈래예요 — 문장은 사람에게 그대로 보여 주고 코드로 가르지 않아요.
        reason = body.get("reason")
        return "contact" if reason == "account_inactive" else "fix_key"
    if t == "space_content_policy":
        return "contact" if no_retry else "retry_later" if code in ("policy_changed", "policy_unavailable") else "fix_request"
    if no_retry:
        return "contact"  # 자동 재전송 안 함(한도 429 · 422 · 504 reason timeout · Idempotency-Key 를 실었으면 4xx upstream_error 도) — 504 timeout 은 요금 없이 끝난 거라 직접 한 번 다시 보내도 돼요(Idempotency-Key 를 실었으면 같은 Idempotency-Key 로)
    if (status == 429 and t == "rate_limit_error") or (status == 503 and t == "api_error"):
        return "retry_later"  # 실행 전 거절이 확인된 429 · 전송 전 503
    if status >= 500 and t == "upstream_error":
        return "retry_later"  # x-should-retry: false 없이 온 5xx upstream_error(529 등)는 실행 전 거절이 확인된 것(과부하 · 모델 회사에 닿기 전 연결 실패)이에요
    if status >= 500:
        return "contact"  # 알려지지 않은 5xx를 자동 재시도하지 않아요
    return "fix_request"  # 400 · 403 · 404 · 4xx upstream_error(벤더 422 포함) — 문장대로 고쳐요

def retry_same_key(e: openai.APIStatusError) -> bool:
    """Idempotency-Key 를 실었을 때만 — call() 이 classify() 보다 먼저 보고, 참이면 잠시 뒤 같은 Idempotency-Key · 같은 본문으로 한 번만 다시 보내요.
    접수 기록을 잠깐 못 읽은 503 두 type · 504 reason timeout 이에요(API 키를 잠깐 못 읽은 503 api_error 는 classify() 가 retry_later 로 가려요)."""
    body = e.body if isinstance(e.body, dict) else {}
    t, reason = body.get("type") or e.type, body.get("reason")
    return (t in ("request_state_unavailable", "request_store_unavailable")
            or (e.status_code == 504 and reason == "timeout"))

def retry_after(e: openai.APIStatusError):
    """글 문이 실은 Retry-After(초) — 잠시 뒤 그대로 다시 보낼 실패에만 와요. 없거나 못 읽으면 None."""
    try:
        return float(e.response.headers.get("retry-after"))
    except (TypeError, ValueError):
        return None

def _held(e: openai.APIStatusError) -> bool:
    """다른 호출이 잡아 둔 몫 때문인가(402 지갑 · 429 이 키의 이번 달 한도) — 잔액 · 한도를 다 쓴 게 아니라 앞 호출이 끝나면 풀려요."""
    body = e.body if isinstance(e.body, dict) else {}
    if e.status_code == 429:
        return body.get("reason") == "held_by_others"
    return e.status_code == 402 and (body.get("reason") == "held_by_others" or "다른 호출이 잡아 둔 몫" in (body.get("message") or ""))

def call(retries=3, held_wait=800, **params):
    """client.chat.completions.create 를 감싸요. retry_later 갈래만 기다렸다 다시 보내요. 실행 불명은 재전송하지 않아요.
    다른 호출이 잡아 둔 몫(402 · 429 의 held_by_others)은 retries 와 따로 — Retry-After(5초)부터 6 · 12 · 24초, 그 뒤로는 30초씩 쉬며(Retry-After 보다 짧게는 안 기다려요) held_wait 초까지 기다려요
    (글 문 앞 호출은 보낸 때부터 약 13분 안에 끝나요 · 영상 · 작업 문 몫은 더 길 수 있어요). 실행 불명 · 시간 초과는 자동으로 다시 보내지 않아요.
    extra_headers 로 Idempotency-Key 를 실었으면 retry_same_key() 갈래만 retries 와 따로 한 번 같은 키 · 같은 본문으로 다시 보내요."""
    attempt, held_for, held_delay = 0, 0.0, 3.0
    keyed, resent = "Idempotency-Key" in (params.get("extra_headers") or {}), False
    while True:
        try:
            return client.chat.completions.create(**params)
        except openai.APIStatusError as e:
            if keyed and not resent and retry_same_key(e):  # classify() 보다 먼저 — 한 번만
                resent = True
                time.sleep(retry_after(e) or 2 + random.random())  # 잠시 뒤 — 2초(+흔들기)는 예시 값
                continue
            action = classify(e)
            if action == "retry_later" and _held(e) and held_for < held_wait:
                wait = min(max(held_delay, retry_after(e) or 0), held_wait - held_for)  # Retry-After 보다 짧게는 안 기다려요
                time.sleep(wait)
                held_for += wait
                held_delay = min(held_delay * 2, 30.0)
                continue
            if action != "retry_later" or attempt >= retries:
                body = e.body if isinstance(e.body, dict) else {}
                raise OnePortError(action, e.status_code, body.get("type") or e.type, body.get("message") or str(e),
                                   body.get("request_id") or e.response.headers.get("request-id")) from e
            # Retry-After 가 있으면 그만큼 · 없으면(실행 전 거절이 확인된 실패) 2 · 4 · 8초(+흔들기)는 예시 값
            time.sleep(retry_after(e) or 2 ** (attempt + 1) + random.random())
            attempt += 1
        # openai.APIConnectionError(시간 초과 포함)는 그대로 올라가요 — 스트림이 아니면 저희가 벤더 답을 다 받은 뒤
        # 끊겼을 수 있어서, 그대로 다시 보내면 두 번 사용할 수 있어요. Idempotency-Key 를 실었으면 같은 키 · 같은 본문으로 한 번
        # 다시 보내요(위 「Idempotency-Key 를 실었을 때」) — 안 실었으면 자동 재전송하지 마세요.

_models = None

def model_info(model):
    """GET /v1/models(키 없이 열려요)의 그 모델 줄 — owned_by · pricing."""
    global _models
    if _models is None:
        with urllib.request.urlopen(f"{BASE}/v1/models", timeout=30) as r:
            _models = {m["id"]: m for m in json.load(r)["data"]}
    return _models.get(model)

def key_resets():
    """오늘 · 이번 달 한도가 다시 열리는 시각(GET /v1/key · 요금 안 붙어요)."""
    req = urllib.request.Request(f"{BASE}/v1/key", headers={"Authorization": f"Bearer {KEY}"})
    with urllib.request.urlopen(req, timeout=30) as r:
        k = json.load(r)
    return {"day": k["day"]["resets_at"], "month": k["month"]["resets_at"]}

def _nb(s):
    return len(s.encode("utf-8")) if isinstance(s, str) else 0

def estimate_cut(model, nbytes):
    """usage 없이 끊긴 스트림을 저희가 사용으로 어림하는 셈. Claude 는 None — 어림하지 않고 벤더가 센 수로 세요. 도중에 끊기면 error 조각 앞 usage 조각에
    그 수가 와요(시작 이벤트 전 실패 · 손님 쪽에서 먼저 끊은 흐름엔 없어요)."""
    m = model_info(model)
    if m is None or m["owned_by"] == "anthropic":
        return None
    tokens = math.ceil(nbytes / 3)  # 받은 글 바이트를 다 더한 뒤 3 으로 나눠 한 번 올림 · 입력은 안 세요 · 글 0 이면 0
    p = m["pricing"]  # pricing.rates 는 [{dimension, unit, unit_label, credits}] 배열이에요
    rate = p.get("output_credits_per_mtok") or next((r["credits"] for r in p.get("rates", []) if r["dimension"] == "output"), 0)
    # 저희 어림과 두 방향으로 달라요 — 끊기기 직전 조각이 못 닿았으면 이 값이 작고, 어림이 예약 금액에서 잘리면 저희 값이 작아요.
    return {"output_tokens": tokens, "credits": tokens * rate / 1_000_000}

def stream_text(**params):
    """스트림으로 받아 글을 모아요. cut=True 면 잘린 답이에요 — 다시 보내면 새 호출이라 또 사용해요.
    elapsed(초)는 마지막으로 보낸 요청이 머리말을 받은 때부터 재요 — call() 이 다시 보내며 기다린 시간은 안 넣어요.
    저희 상한(약 12분 50초 · 요청 하나마다 새로)은 모델 회사로 보내기 시작한 때부터 재서(머리말을 기다린 시간 포함) elapsed 로는 못 갈라요.
    마지막으로 요청을 보낸 때부터 770초 남짓에서 끊겼으면 상한이에요 — 그대로 다시 보내도 또 끊기니 과제를 나눠 보내요.
    조각 사이 침묵으로 먼저 끊지 마세요 — 침묵은 저희가 벤더 바이트로 재요(Claude 는 생각 글을 조각으로 안 넘겨요)."""
    stream = call(**params, stream=True)  # 시작 전 실패는 여기서 OnePortError 로 와요
    started = time.monotonic()  # 머리말을 받은 때 — call() 이 기다린 시간은 빼요
    text, nbytes, usage, finished, error = [], 0, None, False, None
    try:
        for chunk in stream:
            if chunk.usage is not None:  # 끝에 usage 만 든 조각(choices 가 빈 배열) · usage.cost_credits 가 이 호출에 쓴 값(정산이 2초 안에 안 끝나면 없어요)
                usage = chunk.usage
            for ch in chunk.choices:
                d = ch.delta
                text.append(d.content or "")
                # 끊김 어림에 세는 칸: 답 글 · 거절 글 · 생각 글(두 칸 중 긴 쪽 하나) · 도구 인자
                nbytes += _nb(d.content) + _nb(getattr(d, "refusal", None))
                nbytes += max(_nb(getattr(d, "reasoning_content", None)), _nb(getattr(d, "reasoning", None)))
                for tc in d.tool_calls or []:
                    nbytes += _nb(tc.function.arguments if tc.function else None)
                fc = getattr(d, "function_call", None)
                nbytes += _nb(fc.arguments if fc else None)
                finished = finished or ch.finish_reason is not None
    except Exception as e:  # 도중 error 조각(openai.APIError · status 없음 · e.body = type · message — Claude 는 저희 시간 제한 · 연결 끊김도 upstream_error 조각) 또는 연결 끊김
        error = e
    estimate = None if usage else estimate_cut(params["model"], nbytes)
    return {"text": "".join(text), "usage": usage, "cut": not finished, "error": error, "estimate": estimate,
            "elapsed": time.monotonic() - started}

# 쓰는 법
# try:
#     out = stream_text(model="gpt-5.6-sol", messages=[{"role": "user", "content": "..."}], max_tokens=2000)
# except OnePortError as e:
#     print(e.action, e.message, key_resets() if e.action in ("day_limit", "month_limit") else "")
TypeScript — openai SDK
// npm i openai — 원포트 오류 처리 감싸개(TypeScript). 갈래는 위 오류 표와 같아요.
import OpenAI, { APIError } from "openai";

const BASE = "https://oneport.kr";
const KEY = process.env.ONEPORT_API_KEY!;
// SDK 자체 재시도는 꺼요(연결 오류 · 시간 초과도 다시 보내 두 번 사용될 수 있어요) — 상태 코드로 온 실패만 아래 call() 이 다시 보내요.
// timeout 은 첫 응답(머리말)까지만 재요(SDK 동작) — 조각 사이 침묵은 저희가 벤더 바이트로 재서 120초에 끊어요(손님 쪽 조각 간격으로 먼저 끊지 마세요).
export const client = new OpenAI({ baseURL: `${BASE}/v1`, apiKey: KEY, timeout: 300_000, maxRetries: 0 });

export type Action = "retry_later" | "fix_request" | "fix_key" | "top_up" | "lower_max_tokens"
  | "shrink_input" | "use_stream" | "day_limit" | "month_limit" | "group_limit" | "use_light_model" | "ask_space_admin" | "contact";

// cause 는 원래 APIError 예요 — 머리글(x-gateway-status-url 등)은 (err.cause as APIError).headers 로 읽어요.
export class OnePortError extends Error {
  constructor(public action: Action, public status: number, public type: string, public detail: string,
              public requestId: string | null, cause?: unknown) {
    super(`[${action}] ${status} ${type}: ${detail}`, { cause });
  }
}

// err.headers 는 SDK v5 부터 Headers, v4 는 일반 객체예요(SDK 동작).
const header = (h: any, name: string): string | null => (typeof h?.get === "function" ? h.get(name) : h?.[name]) ?? null;
// err.message 는 「429 문장」처럼 상태 코드가 앞에 붙어요 — 문장은 err.error.message 로 읽어요.
const inner = (err: APIError) => (err.error ?? {}) as { type?: string; message?: string; code?: string; reason?: string; request_id?: string; status_url?: string };
// 글 문이 실은 Retry-After(초) — 잠시 뒤 그대로 다시 보낼 실패에만 와요. 없거나 못 읽으면 null.
const retryAfterMs = (err: APIError): number | null => {
  const s = Number(header(err.headers, "retry-after"));
  return Number.isFinite(s) && s > 0 ? s * 1000 : null;
};

export function classify(err: APIError): Action {
  const { type: t = err.type ?? "", message: msg = "", code, reason } = inner(err);
  const status = err.status ?? 0;
  const noRetry = header(err.headers, "x-should-retry") === "false";
  if (["upstream_execution_unconfirmed", "request_already_exists", "request_state_unavailable", "request_store_unavailable"].includes(t)) return "contact"; // 422 · 409 는 받은 상태 주소를 GET 조회(없으면 요청 ID와 시각으로 문의) · 503 두 type 은 같은 키로 한 번 직접(위 문단)
  if (t === "insufficient_credit") {
    // 같은 지갑의 다른 호출이 잡아 둔 몫 때문 — 그 호출이 끝나 정산되면 풀려요(동시에 보내는 수를 줄이면 덜 나요).
    // 기계가 읽는 칸(reason)을 먼저 보고, 없으면 문장으로 가려요.
    // 키를 실어도 이 402 엔 대개 x-should-retry: false 가 없어요(접수 기록을 못 적었을 때만 붙어요) — 붙어 왔으면 자동으로 다시 보내지 말고 받은 조회 주소를 GET 해요.
    if (reason === "held_by_others" || msg.includes("다른 호출이 잡아 둔 몫")) return noRetry ? "contact" : "retry_later";
    // 임베딩 · 그림 · 소리 문 — 이 요청 몫이 잔액보다 커요. 문장이 말한 것(묶음 · 참고 그림 · 글 · 파일 길이)을 줄여 보내요.
    if (reason === "hold_exceeds_balance" && !msg.startsWith("이 요청에 필요한")) return "shrink_input";
    if (!msg.startsWith("이 요청에 필요한")) return "top_up"; // 잔액이 최소치보다 적어요 — https://oneport.kr/buy
    if (msg.includes("stream: true 로 보내거나")) return "use_stream";
    // 몫 대부분이 입력이면 max_tokens 를 줄여도 거의 안 줄어요 — 첨부 · 대화 기록을 줄이거나 나눠 보내요.
    return msg.includes("미리 잡는 몫 대부분이 입력") ? "shrink_input" : "lower_max_tokens";
  }
  // 오늘 한도: 쓴 몫만 봐서 max_tokens 를 줄여도 같아요 → day.resets_at 까지 기다려요.
  // key_month_limit: 쓴 몫과 이 요청 최대 몫만으로 이번 달 한도를 넘었어요 — max_tokens 를 줄이면 될 수 있어요 → 아니면 month.resets_at.
  // held_by_others: 같은 키로 아직 끝나지 않은 호출 몫까지 더하면 넘어요 — 그 호출이 끝나면 풀려서 call() 이 기다렸다 그대로 다시 보내요.
  // 모든 문이 reason(key_day_limit · key_month_limit · held_by_others)으로 와요 — 없으면(작업 문을 다시 조회한 응답) 문장으로 갈라요.
  // 이번 달 한도도 몫 대부분이 입력이면 max_tokens 를 줄여도 거의 안 줄어요 — 첨부 · 대화 기록을 줄이거나 나눠 보내요.
  if (t === "key_limit_exceeded") {
    // 이 429 엔 x-should-retry: true 가 붙어요 — false 로 왔으면 접수 기록을 못 적은 것이라 받은 조회 주소를 GET 해요.
    if (reason === "held_by_others") return noRetry ? "contact" : "retry_later";
    if (reason === "key_day_limit" || (reason === undefined && msg.includes("오늘"))) return "day_limit";
    return msg.includes("미리 잡는 몫 대부분이 입력") ? "shrink_input" : "month_limit";
  }
  // 갈래는 error.reason(위 표) — group_budget 은 남은 몫이 있으면 상한을 줄여서, group_tail 은 단가가 낮은 모델로.
  if (t === "group_limit_exceeded") {
    if (reason === "group_closed" || reason === "group_not_started" || reason === "group_ended") return "ask_space_admin";
    if (reason === "group_tail") return "use_light_model";
    // 모르는 reason 이 오면 아래 문장 낱말로 갈라요.
    if (reason !== "group_budget" && (msg.includes("그룹이 닫혀") || msg.includes("부터 쓸 수 있어요") || (msg.includes("기간이") && msg.includes("끝났어요")))) return "ask_space_admin";
    return msg.includes("미리 잡는 몫 대부분이 입력") ? "shrink_input" : "group_limit";
  }
  if (t === "group_member_limit_exceeded") return "ask_space_admin"; // 웹 채팅의 1인 몫이라 API 키엔 안 와요
  // 갈래는 reason 으로(「인증」 장 표) — 지갑이 멈췄으면(account_inactive) 키를 고칠 일이 아니에요.
  // reason 이 없으면(관리 키 문 /v1/keys) 키를 고칠 갈래예요 — 문장은 사람에게 그대로 보여 주고 코드로 가르지 않아요.
  if (t === "authentication_error") return reason === "account_inactive" ? "contact" : "fix_key";
  if (t === "space_content_policy") return noRetry ? "contact" : code === "policy_changed" || code === "policy_unavailable" ? "retry_later" : "fix_request";
  if (noRetry) return "contact"; // 자동 재전송 안 함(한도 429 · 422 · 504 reason timeout · Idempotency-Key 를 실었으면 4xx upstream_error 도) — 504 timeout 은 요금 없이 끝난 거라 직접 한 번 다시 보내도 돼요(Idempotency-Key 를 실었으면 같은 Idempotency-Key 로)
  // 실행 전 거절이 확인된 429 · 전송 전 503 · x-should-retry: false 없이 온 5xx upstream_error(529 등 — 과부하 · 모델 회사에 닿기 전 연결 실패로 실행 전 거절이 확인된 것)만 다시 보내요.
  if ((status === 429 && t === "rate_limit_error") || (status === 503 && t === "api_error")) return "retry_later";
  if (status >= 500 && t === "upstream_error") return "retry_later";
  if (status >= 500) return "contact"; // 알려지지 않은 5xx를 자동 재시도하지 않아요
  return "fix_request"; // 400 · 403 · 404 · 4xx upstream_error(벤더 422 포함) — 문장대로 고쳐요
}

/**
 * Idempotency-Key 를 실었을 때만 — call() 이 classify() 보다 먼저 보고, 참이면 잠시 뒤 같은 Idempotency-Key · 같은 본문으로 한 번만 다시 보내요.
 * 접수 기록을 잠깐 못 읽은 503 두 type · 504 reason timeout 이에요(API 키를 잠깐 못 읽은 503 api_error 는 classify() 가 retry_later 로 가려요).
 */
export const retrySameKey = (err: APIError): boolean => {
  const { type: t, reason } = inner(err);
  return t === "request_state_unavailable" || t === "request_store_unavailable"
    || (err.status === 504 && reason === "timeout");
};

/** 다른 호출이 잡아 둔 몫 때문인가(402 지갑 · 429 이 키의 이번 달 한도) — 잔액 · 한도를 다 쓴 게 아니라 앞 호출이 끝나면 풀려요. */
const heldByOthers = (err: APIError) => {
  const { reason, message = "" } = inner(err);
  if (err.status === 429) return reason === "held_by_others";
  return err.status === 402 && (reason === "held_by_others" || message.includes("다른 호출이 잡아 둔 몫"));
};
const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
/**
 * chat.completions.create 를 감싸요. retry_later 갈래만 기다렸다 다시 보내요. 실행 불명은 재전송하지 않아요.
 * 다른 호출이 잡아 둔 몫(402 · 429 의 held_by_others)은 retries 와 따로 — Retry-After(5초)부터 6 · 12 · 24초, 그 뒤로는 30초씩 쉬며(Retry-After 보다 짧게는 안 기다려요) heldWaitMs 까지 기다려요(글 문 앞 호출은 보낸 때부터 약 13분 안에 끝나요 · 영상 · 작업 문 몫은 더 길 수 있어요).
 * 실행 불명 · 시간 초과는 자동으로 다시 보내지 않아요.
 * headers 는 그대로 create 의 둘째 인자로 실어요 — Idempotency-Key 는 call(params, 3, 800_000, { "Idempotency-Key": key }) 처럼 넘기고, 다시 보낼 때도 같은 객체예요.
 * 그렇게 키를 실었으면 retrySameKey() 갈래만 retries 와 따로 한 번 같은 키 · 같은 본문으로 다시 보내요.
 */
export function call(params: OpenAI.Chat.ChatCompletionCreateParamsNonStreaming, retries?: number, heldWaitMs?: number, headers?: Record<string, string>): Promise<OpenAI.Chat.ChatCompletion>;
export function call(params: OpenAI.Chat.ChatCompletionCreateParamsStreaming, retries?: number, heldWaitMs?: number, headers?: Record<string, string>): Promise<AsyncIterable<OpenAI.Chat.ChatCompletionChunk>>;
export async function call(params: OpenAI.Chat.ChatCompletionCreateParams, retries = 3, heldWaitMs = 800_000, headers?: Record<string, string>): Promise<unknown> {
  let attempt = 0, heldFor = 0, heldDelay = 3_000, resent = false;
  const keyed = headers?.["Idempotency-Key"] !== undefined;
  for (;;) {
    try {
      return await client.chat.completions.create(params, headers ? { headers } : undefined);
    } catch (err) {
      // 연결 오류 · 시간 초과(status 없음)는 그대로 던져요 — 스트림이 아니면 저희가 벤더 답을 다 받은 뒤
      // 끊겼을 수 있어서, 그대로 다시 보내면 두 번 사용할 수 있어요. Idempotency-Key 를 실었으면 같은 키 · 같은 본문으로 한 번
      // 다시 보내요(위 「Idempotency-Key 를 실었을 때」) — 안 실었으면 자동 재전송하지 마세요.
      if (!(err instanceof APIError) || err.status === undefined) throw err;
      if (keyed && !resent && retrySameKey(err)) { // classify() 보다 먼저 — 한 번만
        resent = true;
        await sleep(retryAfterMs(err) ?? 2_000 + Math.random() * 1000); // 잠시 뒤 — 2초(+흔들기)는 예시 값
        continue;
      }
      const action = classify(err);
      if (action === "retry_later" && heldByOthers(err) && heldFor < heldWaitMs) {
        const wait = Math.min(Math.max(heldDelay, retryAfterMs(err) ?? 0), heldWaitMs - heldFor); // Retry-After 보다 짧게는 안 기다려요
        await sleep(wait);
        heldFor += wait;
        heldDelay = Math.min(heldDelay * 2, 30_000);
        continue;
      }
      if (action !== "retry_later" || attempt >= retries) {
        const { type, message, request_id } = inner(err);
        throw new OnePortError(action, err.status, type ?? err.type ?? "", message ?? err.message, request_id ?? header(err.headers, "request-id"), err);
      }
      // Retry-After 가 있으면 그만큼 · 없으면(실행 전 거절이 확인된 실패) 2 · 4 · 8초(+흔들기)는 예시 값
      await sleep(retryAfterMs(err) ?? 2 ** (attempt + 1) * 1000 + Math.random() * 1000);
      attempt++;
    }
  }
}

let models: Map<string, any> | null = null;
/** GET /v1/models(키 없이 열려요)의 그 모델 줄 — owned_by · pricing. */
export async function modelInfo(id: string): Promise<any> {
  models ??= new Map(((await (await fetch(`${BASE}/v1/models`)).json()).data as any[]).map((m) => [m.id, m]));
  return models.get(id);
}

/** 오늘 · 이번 달 한도가 다시 열리는 시각(GET /v1/key · 요금 안 붙어요). */
export async function keyResets(): Promise<{ day: string; month: string }> {
  const k = await (await fetch(`${BASE}/v1/key`, { headers: { Authorization: `Bearer ${KEY}` } })).json();
  return { day: k.day.resets_at, month: k.month.resets_at };
}

const nb = (s: unknown) => (typeof s === "string" ? new TextEncoder().encode(s).length : 0);

/** usage 없이 끊긴 스트림을 저희가 사용으로 어림하는 셈. Claude 는 null — 어림하지 않고 벤더가 센 수로 세요. 도중에 끊기면 error 조각 앞 usage 조각에 그 수가 와요(시작 이벤트 전 실패 · 손님 쪽에서 먼저 끊은 흐름엔 없어요). */
export async function estimateCut(model: string, nbytes: number) {
  const m = await modelInfo(model);
  if (!m || m.owned_by === "anthropic") return null;
  const tokens = Math.ceil(nbytes / 3); // 받은 글 바이트를 다 더한 뒤 3 으로 나눠 한 번 올림 · 입력은 안 세요 · 글 0 이면 0
  // pricing.rates 는 [{dimension, unit, unit_label, credits}] 배열이에요
  const rate = m.pricing.output_credits_per_mtok ?? m.pricing.rates?.find((r: any) => r.dimension === "output")?.credits ?? 0;
  // 저희 어림과 두 방향으로 달라요 — 끊기기 직전 조각이 못 닿았으면 이 값이 작고, 어림이 예약 금액에서 잘리면 저희 값이 작아요.
  return { outputTokens: tokens, credits: (tokens * rate) / 1_000_000 };
}

/**
 * 스트림으로 받아 글을 모아요. cut 이 true 면 잘린 답이에요 — 다시 보내면 새 호출이라 또 사용해요.
 * elapsedMs 는 마지막으로 보낸 요청이 머리말을 받은 때부터 재요 — call() 이 다시 보내며 기다린 시간은 안 넣어요.
 * 저희 상한(약 12분 50초 · 요청 하나마다 새로)은 모델 회사로 보내기 시작한 때부터 재서(머리말을 기다린 시간 포함) elapsedMs 로는 못 갈라요.
 * 마지막으로 요청을 보낸 때부터 770초 남짓에서 끊겼으면 상한이에요 — 그대로 다시 보내도 또 끊기니 과제를 나눠 보내요.
 * 조각 사이 침묵으로 먼저 끊지 마세요 — 침묵은 저희가 벤더 바이트로 재요(Claude 는 생각 글을 조각으로 안 넘겨요).
 */
export async function streamText(params: Omit<OpenAI.Chat.ChatCompletionCreateParamsStreaming, "stream">) {
  const stream = await call({ ...params, stream: true }); // 시작 전 실패는 여기서 OnePortError 로 와요
  const started = Date.now(); // 머리말을 받은 때 — call() 이 기다린 시간은 빼요
  let text = "", nbytes = 0, finished = false;
  let usage: OpenAI.CompletionUsage | null = null, error: unknown = null;
  try {
    for await (const chunk of stream) {
      if (chunk.usage) usage = chunk.usage; // 끝에 usage 만 든 조각(choices 가 빈 배열) · usage.cost_credits 가 이 호출에 쓴 값(정산이 2초 안에 안 끝나면 없어요)
      for (const ch of chunk.choices) {
        const d = ch.delta as any; // reasoning_content · reasoning 은 SDK 타입에 없는 칸이에요
        text += d.content ?? "";
        // 끊김 어림에 세는 칸: 답 글 · 거절 글 · 생각 글(두 칸 중 긴 쪽 하나) · 도구 인자
        nbytes += nb(d.content) + nb(d.refusal) + Math.max(nb(d.reasoning_content), nb(d.reasoning));
        for (const tc of d.tool_calls ?? []) nbytes += nb(tc.function?.arguments);
        nbytes += nb(d.function_call?.arguments);
        if (ch.finish_reason) finished = true;
      }
    }
  } catch (err) {
    error = err; // 도중 error 조각(APIError · status 없음 · err.error = type · message — Claude 는 저희 시간 제한 · 연결 끊김도 upstream_error 조각) 또는 연결 끊김
  }
  const estimate = usage ? null : await estimateCut(params.model, nbytes);
  return { text, usage, cut: !finished, error, estimate, elapsedMs: Date.now() - started };
}

// 쓰는 법
// try { const out = await streamText({ model: "gpt-5.6-sol", messages: [{ role: "user", content: "..." }], max_tokens: 2000 }); }
// catch (e) { if (e instanceof OnePortError) console.log(e.action, e.detail, e.action === "day_limit" || e.action === "month_limit" ? await keyResets() : ""); }

잘린 답 이어 받기#

스트림이 finish_reason(/v1/messages 는 message_stop · /v1/responses 는 response.completed) 없이 끝나면 잘린 답이에요 — 도중 error 조각이 왔거나 연결이 끊긴 경우예요(Claude 를 /v1/chat/completions 로 받으면 저희 시간 제한 · 벤더 연결 끊김도 error 조각(type upstream_error)으로 오고, 바로 앞 usage 조각에 그때까지 쓴 토큰 · cost_credits 가 와요). 처음부터 다시 부르면 이미 받은 몫까지 다시 사용하니, 받은 글을 저장해 두었다가 이어 받으세요. ① 받은 글을 모아 둬요. ② 원래 messages 뒤에 받은 글을 assistant 메시지로, 그다음에 「앞 답이 끊겼어요. 끊긴 곳 바로 뒤부터 이어서 써 주세요」 user 메시지를 붙여요. ③ 같은 모델로 다시 불러 받은 글 뒤에 이어 붙여요. 마지막을 assistant 로 끝내서 그 뒤를 잇게 하는 방식(prefill)은 지금 목록의 Claude 대부분(4.6 이후)이 400 으로 거절해요(벤더 동작 · 저희는 4xx upstream_error 로 전해요) — 그래서 끝을 user 메시지로 둬요. 도구 호출(tool_calls · tool_use)과 생각 블록은 반쯤 받은 것을 못 이어서 그 턴은 처음부터 다시 받아야 해요 — 이어 받는 건 글 조각뿐이에요. 이어 받기도 앞 대화와 받은 글을 입력으로 다시 사용해요. finish_reason 이 length 면 잘린 게 아니라 출력 상한에 닿은 것이라 max_tokens 를 올리거나, 같은 방법으로 이어 받으면 돼요.

Python — openai SDK(/v1/chat/completions · 어느 회사 모델이든 같아요)
import os
from openai import OpenAI, APIError

client = OpenAI(api_key=os.environ["ONEPORT_API_KEY"], base_url="https://oneport.kr/v1", timeout=300, max_retries=0)

CONTINUE = "앞 답이 끊겼어요. 끊긴 곳 바로 뒤부터 이어서 써 주세요 — 앞부분은 다시 쓰지 마세요."


def stream_once(messages, model, max_tokens):
    """한 번 부르고 (받은 글, finish_reason) — 잘리면 finish_reason 이 None 이에요."""
    # 시작 전 실패(4xx · 5xx)는 여기서 그대로 올라가요 — 위 「그대로 쓰는 감싸개」로 다루세요.
    stream = client.chat.completions.create(model=model, messages=messages, max_tokens=max_tokens, stream=True)
    got, finish = [], None
    try:
        for chunk in stream:
            for choice in chunk.choices:
                if choice.delta.content:
                    got.append(choice.delta.content)
                if choice.finish_reason:
                    finish = choice.finish_reason
    except APIError:  # 도중 error 조각 · 연결 끊김 — 받은 데까지는 남겨요
        pass
    return "".join(got), finish


def stream_with_resume(messages, model="claude-sonnet-5", max_tokens=4000, tries=2):
    text, finish = stream_once(messages, model, max_tokens)
    while finish is None and text and tries > 0:
        tries -= 1
        more, finish = stream_once(
            messages
            + [
                {"role": "assistant", "content": text},  # 받은 글 — 맨 끝이 아니라서 prefill 이 아니에요
                {"role": "user", "content": CONTINUE},
            ],
            model,
            max_tokens,
        )
        text += more
    return text, finish  # finish 가 None 이면 이어 받기까지 잘렸어요 — 받은 글을 보관하고 잠시 뒤 다시

자주 만나는 실패#

무엇을 했을 때오는 값저희가 하는 일
없는 모델 이름404 · model_not_found가장 가까운 이름을 같이 드려요. 시키지 않은 모델로 몰래 바꾸지 않아요.
그림 모델을 채팅 문으로400 · invalid_request_error「없다」고 하지 않고 어느 문으로 가야 하는지 문장에 적어 드려요.
Claude 5 에 temperature안 나요 — 빼고 넘겨요어느 문 · 어느 판이든 빼고 넘기고 헤더 x-gateway-ignored-params 에 적어요. 모델이 어차피 안 읽는 값이라 답은 같아요.
anthropic-version 2026-10-21 판에 temperature · top_p · top_k400 · invalid_request_error그 판은 세 칸을 받지 않아요(벤더 동작). 값을 읽는 Claude(claude-haiku-4-5 등)면 보내기 전에 막아요 — 빼시거나 anthropic-version: 2023-06-01 을 주세요.
잔액보다 큰 max_tokens402 · insufficient_credit벤더로 안 보내요. 요금이 안 붙으니 값을 줄여 다시 보내시면 돼요.
클로드·GPT 팩 크레딧으로 제미나이403 · model_not_in_plan벤더로 안 보내고 요금도 안 붙어요. 부를 수 있는 모델 이름을 같이 드려요.
벤더가 잠시 조임보통 안 보여요같은 모델의 다른 경로로 다시 걸어요. 몇 번째에 됐는지 x-gateway-fallback-depth 에 담겨요.
모델 회사로 보낸 뒤 실행 결과 불명422 · upstream_execution_unconfirmed다른 경로로 넘기지 않아요. x-should-retry: false 를 따르고, 받은 상태 조회 주소가 있으면 GET으로 확인해 주세요.

증상별로 찾기#