요청 한도

한도는 성격이 다른 세 가지입니다. 셋을 섞어 생각하면 402 와 429 를 구분할 수 없습니다.

잔액 한도

모든 추론 요청은 시작 전에 잔액을 확인합니다. 잔액이 부채 허용선 아래로 내려가면 요청이 거절됩니다. 허용선은 서비스 정책 값이며 기본은 5,000원입니다. 즉 잔액이 −5,000원 이하가 되면 막힙니다.

이 완충이 있는 이유는, 요청을 받기 전에는 그 요청이 얼마짜리인지 알 수 없기 때문입니다. 잔액을 0원에서 딱 끊으면 긴 응답 하나가 항상 음수 잔액을 만들고 그 다음 요청이 전부 실패합니다.

{
  "error": {
    "code": 402,
    "message": "크레딧이 부족합니다.",
    "metadata": { "error_type": "insufficient_credits", "balance_krw": "-5200.000000" }
  }
}

잔액이 0 이하로 내려가면 그 계정의 키는 자동으로 정지되고, 충전하면 자동으로 풀립니다. 충전 방법은 크레딧과 결제에 있습니다.

현재 상태는 GET /credits로 확인합니다.

curl https://openrouter.myip.co.kr/api/v1/credits \
  -H "Authorization: Bearer $MYIP_API_KEY"

{ "data": { "total_credits": 50000, "total_usage": 12750.482 } }

total_credits 는 지금까지 충전·보너스로 들어온 금액의 합, total_usage 는 차감·소멸의 합입니다. 둘 다 원(₩)이고, 잔액은 그 차입니다.

키 한도

키마다 사용 한도를 걸 수 있습니다. 한도는 limit(원)과 limit_reset(never · daily · weekly · monthly) 두 값으로 정합니다. 기간 경계는 Asia/Seoul 기준입니다.

한도 검사는 요청을 업스트림에 보내기 전에 합니다. 해당 기간의 사용액 합이 한도 이상이면 그 자리에서 402 입니다.

{
  "error": {
    "code": 402,
    "message": "키 사용 한도를 초과했습니다.",
    "metadata": {
      "error_type": "key_limit_exceeded",
      "limit_krw": "50000.000000",
      "usage_krw": "50000.000000"
    }
  }
}

남은 한도는 GET /key에서 봅니다.

{
  "data": {
    "limit": 50000,
    "usage": 12750.482,
    "limit_remaining": 37249.518,
    "limit_reset": "monthly",
    "usage_daily": 820.4,
    "usage_weekly": 4102.9,
    "usage_monthly": 12750.482
  }
}

limit 이 null 이면 그 키에는 한도가 없고 계정 잔액만 적용됩니다. 한도는 관리 키로 PATCH /keys/{hash}를 불러 바꿉니다.

요청 빈도 제한

/api/v1/ 전체에 대해 클라이언트 IP 당 초당 30요청, 순간 버스트 60요청까지 허용합니다. 이를 넘으면 429 입니다.

{
  "error": {
    "code": 429,
    "message": "요청이 너무 잦습니다. 잠시 후 다시 시도하세요.",
    "metadata": { "error_type": "rate_limit_exceeded" }
  }
}

GET /key 응답의 rate_limit 필드({"requests":1000,"interval":"1h"})는 openrouter 형상 호환을 위한 고정값이며 실제로 강제되는 한도가 아닙니다. 응답 자체가 note 로 "deprecated 이니 무시해도 된다"고 적어 두었습니다. 실제 제한은 위의 초당 30요청입니다.

동시 요청

계정이나 키 단위의 동시 요청 상한은 두지 않습니다. 다만 로컬 GPU 슬롯의 처리 용량은 유한하므로, 같은 로컬 모델에 동시 요청이 몰리면 큐가 생겨 지연이 늘어납니다. 오류가 나는 것이 아니라 느려집니다.

처리량이 필요하면 models[] 로 후보를 여러 개 주거나 provider.sort: "throughput" 을 쓰세요(Provider 라우팅).

시간과 크기 제한

프롬프트가 로컬 모델의 컨텍스트를 넘으면 그 후보는 보내기 전에 체인에서 빠집니다. 콜드스타트 시간을 낭비하지 않으려는 것입니다. 대신 쓸 후보가 있으면 그쪽으로 넘어가고, 없으면 404 no_endpoints_found 입니다.

우리 로컬 GPU 모델의 컨텍스트는 다음과 같습니다.

최신 값은 GET /models의 context_length 와 top_provider.max_completion_tokens 에서 확인하세요.

한도에 걸렸을 때

관련 문서: 사용 한도와 402, 요금 계산 방식.