오류
Starmodel 게이트웨이의 모든 오류는 안정적인 code 를 담은 구조화된 JSON 본문을 반환합니다. 사람이 읽는 message 가 아니라 code 로 분기하세요.
오류 형식
모든 오류는 하나의 엔벨로프를 공유합니다:
{ "error": { "code": "insufficient_credits", "message": "Insufficient credits. Please top up and try again.", "type": "error" }}Anthropic 호환 /v1/messages 엔드포인트는 대신 Anthropic 고유 형식으로 오류를 반환합니다 — 최상위 type: "error" 와 type, message 를 담은 중첩된 error 객체입니다.
자주 발생하는 오류
| 상태 | 코드 | 의미 |
|---|---|---|
401 | unauthorized | 누락되었거나 유효하지 않거나 비활성화된 API 키입니다. |
403 | model_not_allowed | 이 API 키는 요청한 모델을 호출할 권한이 없습니다. |
400 | invalid_model | model 값이 알려진 모델 id가 아닙니다. |
400 | no_available_channel | 현재 이 모델에 사용할 수 있는 업스트림 채널이 없습니다. |
402 | insufficient_credits | 지갑 잔액이 요청을 처리하기에 부족합니다. |
402 | subscription_quota_exceeded | 이번 주기의 구독 토큰 할당량을 모두 사용했습니다. |
400 | model_pricing_missing | 이 모델에는 게시된 판매가가 없어 아직 과금할 수 없습니다. |
429 | rpm_exceeded | 분당 요청 수 한도를 초과했습니다. |
429 | tpm_exceeded | 분당 토큰 수 한도를 초과했습니다. |
429 | concurrency_exceeded | 동시 요청이 너무 많습니다. |
502 | upstream_error | 업스트림 제공자가 오류를 반환했습니다. |
500 | internal | 예기치 않은 게이트웨이 오류 — 재시도한 뒤에도 계속되면 지원팀에 문의하세요. |
요청 한도와 재시도
429 응답에는 Retry-After 헤더(초 단위)가 포함됩니다 — 그만큼 기다린 후 재시도하세요. rpm_exceeded / tpm_exceeded 는 분당 요청 수 / 토큰 수 한도이고, concurrency_exceeded 는 동시에 처리 중인 요청이 너무 많음을 의미합니다.
결제와 가격
402 는 지갑 잔액으로 요청을 감당할 수 없다는 의미입니다 — 충전(insufficient_credits)하거나 다음 주기를 기다리세요(subscription_quota_exceeded). 400 의 model_pricing_* / model_not_billable 코드는 모델에 게시된 판매가가 아직 없다는 뜻이니, 관리자에게 가격 설정 및 게시를 요청하세요.
오류 처리
프로그램에서 분기하려면 error.code 를 읽으세요 — 안정적입니다. error.message 는 사람을 위한 것이며 바뀔 수 있습니다. 429 와 502 는 백오프 후 재시도하고, 4xx 결제·검증 오류는 요청을 먼저 수정하지 않고 재시도하지 마세요.