에러
상태 코드와 대응 방법, 그리고 증상별로 찾아가는 자리.
에러 몸통은 부르신 문의 형식을 따라요 — OpenAI 형식 문과 /v1/messages 의 모양이 다르니 파서를 짜실 때 보세요. 어느 쪽이든 type 값은 같고, 분기는 type 으로 하세요(OpenAI 형식의 code 는 type 과 같아요). 스페이스 전송 정책에 걸린 경우(type space_content_policy)만 code 에 세부 이유(blocked_term 등)가 따로 와요.
{
"error": {
"type": "model_not_found",
"message": "지원하지 않는 모델이에요: claude-sonet-5. 이건 어떠세요: claude-sonnet-5. 전체 목록은 GET /v1/models 에 있어요.",
"code": "model_not_found"
}
}{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "이 문은 anthropic 모델만 받아요."
}
}| 코드 | type | 다시 보내나 | SDK 예외 클래스 | 뜻과 대응 |
|---|---|---|---|---|
| 400 | invalid_request_error | 고쳐서 — 문장이 고칠 곳을 말해요 | BadRequestError | 요청 형식이나 문이 안 맞아요. 파는 모델인데 문이 틀린 경우도 여기로 와요 — 그때는 어느 문으로 가야 하는지 문장에 적어 드려요. |
| 401 | authentication_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 이 없어서 문장을 그대로 보여 주세요. |
| 402 | insufficient_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 문장 끝도 이렇게 누가 충전할지를 말해요. |
| 403 | model_not_in_plan | 고쳐서 — 문장이 준 모델로 | PermissionDeniedError | 이 크레딧으로 못 부르는 모델이에요 — 제미나이는 제미나이 팩이나 모델을 정하지 않은 크레딧으로 불러요. 요금이 붙기 전에 나고, 바꿔 넣을 모델 이름을 문장에 같이 드려요. |
| 403 | student_key_blocked | 고쳐서 — 문장이 말한 도구 · 칸을 빼거나 모델을 바꿔요 | PermissionDeniedError | 학생 키로 웹 검색 · 웹 페이지 읽기 · 다른 서버의 도구(원격 MCP) · 영상 만들기 · jev · 작업(/v1/tasks)을 불렀어요(검색이 붙은 모델 · web_search_options 같은 검색 칸 포함). 요금이 붙기 전에 나고, 빼야 할 도구 · 칸 이름이나 바꿔야 할 모델을 문장에 적어 드려요. Codex CLI 는 웹 검색을 늘 실어 보내니 web_search = "disabled" 로 꺼 주세요. 키를 나눠 준 분이 그 키를 선생님 키로 바꾸면 열려요. |
| 403 | model_disabled_in_space | 고쳐서 — 켜진 모델로 | PermissionDeniedError | 스페이스 관리자가 끈 모델이에요. 키가 붙은 그룹에서만 끈 모델도 이 type 이고, 그때는 그룹 이름을 문장에 적어 드려요. 요금이 붙기 전에 나고, 켜진 모델 이름을 문장에 같이 드려요. 내 키로 GET /v1/models 를 부르시면 켜진 모델만 나와요. |
| 403 | student_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). |
| 403 | connector_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). |
| 404 | model_not_found | 고쳐서 — GET /v1/models 의 id 로 | NotFoundError | 그 이름의 모델이 없어요. 응답에 가장 가까운 이름을 같이 드려요. 모델 목록을 잠깐 못 읽으면 404 가 아니라 503 api_error(Retry-After: 2)예요 — 404 면 이름을 고쳐요. |
| 404 | not_found_error | 고쳐서 — 문장이 맞는 주소를 알려 줘요 | NotFoundError | 없는 주소예요. 문장에 고칠 방법(/v1 두 번 · 옛 completions · 묶음 처리 등)을 적어 드려요. 묶음 처리 문(/v1/batches)은 없어요 — 여러 건은 한 건씩 보내 주세요(동시에 보내셔도 돼요 · 지갑 몫은 아래 「402 는 호출 전에 나요」). 커넥터 부탁 한 줄 조회(GET /v1/connectors/requests/{id})에선 id 가 UUID 꼴이 아니거나 이 지갑의 부탁이 아닌 거예요. |
| 429 | key_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 로 넣어 보내라고 해요). 분당 제한은 저희가 안 걸어요. |
| 429 | rate_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)로 드려요. |
| 429 | group_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 이 오면 문장으로 갈라요(아래 감싸개). |
| 429 | group_member_limit_exceeded | 멈춤 — 웹 채팅 몫이에요 | RateLimitError(세 갈래 다 — type 으로 갈라요) | 웹 채팅에서 강좌 안 내 몫(1인 몫)에 닿았어요. 다시 보내도 안 풀려요(x-should-retry: false). API 키에는 안 와요 — API 키의 한 사람 몫은 키의 이번 달 · 오늘 한도(key_limit_exceeded)예요. |
| 429 | too_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 · 5xx | upstream_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 · 503 | space_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 동작). |
| 422 | upstream_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 는 벤더가 요청을 거절한 경우라 요청을 고쳐야 해요. |
| 422 | school_guard_blocked | 고쳐서 — 표현을 바꿔요 · x-should-retry: false | UnprocessableEntityError | 학생 키로 보낸 글이 유해 문장 검사에 걸려 모델로 보내지 않았어요. 요금은 안 붙어요. 자해에 관한 글이면 문장이 자살예방상담전화 109 를 알려 드려요. |
| 503 | api_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() 이 해요). |
| 503 | school_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 를 실었을 때」).
# 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 "")// 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 를 올리거나, 같은 방법으로 이어 받으면 돼요.
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_k | 400 · invalid_request_error | 그 판은 세 칸을 받지 않아요(벤더 동작). 값을 읽는 Claude(claude-haiku-4-5 등)면 보내기 전에 막아요 — 빼시거나 anthropic-version: 2023-06-01 을 주세요. |
| 잔액보다 큰 max_tokens | 402 · insufficient_credit | 벤더로 안 보내요. 요금이 안 붙으니 값을 줄여 다시 보내시면 돼요. |
| 클로드·GPT 팩 크레딧으로 제미나이 | 403 · model_not_in_plan | 벤더로 안 보내고 요금도 안 붙어요. 부를 수 있는 모델 이름을 같이 드려요. |
| 벤더가 잠시 조임 | 보통 안 보여요 | 같은 모델의 다른 경로로 다시 걸어요. 몇 번째에 됐는지 x-gateway-fallback-depth 에 담겨요. |
| 모델 회사로 보낸 뒤 실행 결과 불명 | 422 · upstream_execution_unconfirmed | 다른 경로로 넘기지 않아요. x-should-retry: false 를 따르고, 받은 상태 조회 주소가 있으면 GET으로 확인해 주세요. |