키움 REST API 429 — 허용된 요청 개수 초과 해결

키움 REST API 자동매매 완전 가이드에서 토큰·TR·WebSocket을 전반적으로 다뤘지만, 429 하나만 검색해서 들어오는 분이 꾸준합니다. 이유는 분명합니다 — 이 오류는 봇이 실제로 돌기 시작한 다음에야 나타나고, 그때는 이미 "어제까지 잘 되던 코드"이기 때문입니다.

이 글은 키움 REST API의 429 한 건만 다룹니다. 한국투자증권 쪽 EGW00201은 별도 글에, 애초에 한도 안에서 돌도록 설계하는 원리는 호출 제한 설계에 있습니다.

1. 응답이 어떻게 생겼나

키움 REST API가 한도를 넘겼다고 판단하면 HTTP 상태코드와 본문 양쪽으로 알려 줍니다.

HTTP/1.1 429 Too Many Requests
Content-Type: application/json

{
  "return_code": 5,
  "return_msg": "허용된 요청 개수를 초과하였습니다"
}

정상 응답과 비교하면 판정 지점이 분명해집니다.

{
  "return_code": 0,
  "return_msg": "정상적으로 처리되었습니다"
}

2. 왜 HTTP 상태코드만 보면 안 되나

키움 REST API는 응답 본문에 return_code·return_msg를 담아 결과를 알려 줍니다. 여기서 실무자가 반드시 지켜야 할 원칙이 나옵니다 — HTTP 상태코드와 return_code를 둘 다 검사해야 합니다.

429는 상태코드로도 드러나는 친절한 경우입니다. 문제는 주문이 거부됐는데 HTTP는 200으로 내려오는 상황입니다. 상태코드만 보고 raise_for_status() 하나로 끝내면, 주문이 안 나간 것을 봇이 모른 채 다음 로직으로 넘어갑니다.

import requests

def call(api_id: str, path: str, body: dict, token: str):
    r = requests.post(
        f"https://api.kiwoom.com{path}",
        headers={
            "authorization": f"Bearer {token}",
            "api-id": api_id,              # 기능 구분 — 정확한 코드는 공식 문서 확인
            "Content-Type": "application/json;charset=UTF-8",
        },
        json=body, timeout=5,
    )

    # ① 속도 문제 — 재시도로 넘길 수 있는 오류
    if r.status_code == 429:
        raise RateLimited(api_id)

    # ② HTTP 200이어도 실패일 수 있다
    data = r.json()
    if data.get("return_code") != 0:
        raise KiwoomError(data.get("return_code"), data.get("return_msg"))

    return data

3. 한도가 걸리는 단위 — 키움과 KIS가 정반대다

이 오류를 오래 못 잡는 분들의 공통점은 KIS에서 쓰던 대응을 그대로 옮긴 경우입니다. 두 증권사는 한도가 걸리는 단위 자체가 다릅니다.

4. 어느 정도 속도가 안전한가

공개된 실측 사례에서는 키움 REST API가 TR 하나당 초당 1회 정도가 안전한 지속 속도이고, 순간적으로 2회 정도까지 버스트가 허용되는 수준으로 보고되고 있습니다. 레거시 OpenAPI+ 시절 흔히 권장되던 초당 약 5회와는 감각이 다릅니다.

5. 처방 — api-id별 토큰 버킷

한도가 TR별로 나뉘어 있으니, 리미터도 api-id를 키로 하는 딕셔너리로 두는 것이 자연스럽습니다. 아래는 스레드 안전한 토큰 버킷 구현입니다.

import time, threading
from collections import defaultdict

class TokenBucket:
    """초당 rate개를 채우고 최대 burst개까지 모아 두는 버킷"""
    def __init__(self, rate=1.0, burst=2):
        self.rate, self.burst = rate, burst
        self.tokens = float(burst)
        self.updated = time.monotonic()
        self.lock = threading.Lock()

    def acquire(self):
        with self.lock:
            now = time.monotonic()
            self.tokens = min(self.burst,
                              self.tokens + (now - self.updated) * self.rate)
            self.updated = now
            if self.tokens < 1.0:
                wait = (1.0 - self.tokens) / self.rate
            else:
                self.tokens -= 1.0
                return
        time.sleep(wait)          # 락 밖에서 대기 — 다른 TR을 막지 않는다
        self.acquire()

# api-id마다 버킷을 따로 — 시세 조회가 주문 경로를 붙잡지 않는다
_buckets = defaultdict(lambda: TokenBucket(rate=1.0, burst=2))

def throttled(api_id: str):
    _buckets[api_id].acquire()

이제 모든 호출이 자기 api-id의 버킷만 소비합니다. 시세 조회가 몰려 대기가 걸려도 주문 TR은 그대로 즉시 통과합니다. 자동매매에서 주문 지연은 곧 슬리피지 비용이라, 이 분리가 실제 손익에 영향을 줍니다.

6. 그래도 뚫리면 — 백오프 + 지터

리미터를 넣어도 429는 완전히 사라지지 않습니다. 네트워크 지연과 서버 측 계측 시점이 어긋나기 때문입니다. 재시도는 반드시 간격을 흩뜨려서 해야 합니다.

import random

class RateLimited(Exception): ...
class KiwoomError(Exception): ...

def with_retry(fn, *args, tries=5, base=0.5, **kw):
    for i in range(tries):
        try:
            return fn(*args, **kw)
        except RateLimited:
            if i == tries - 1:
                raise
            # 지수 백오프 + 지터 — 막힌 요청들이 같은 시점에 다시 몰리는 것을 막는다
            time.sleep(base * (2 ** i) + random.uniform(0, 0.3))
        # KiwoomError는 잡지 않는다 — 사람이 손대야 끝나는 오류다

7. 조회가 많아서 걸리는 경우 — WebSocket으로 옮기기

리미터를 제대로 넣었는데도 계속 걸린다면, 대개 호출 구조 자체가 한도를 넘게 설계돼 있습니다. 전형적인 형태가 종목별 REST 폴링입니다.

키움 REST API는 실시간 시세를 WebSocket으로 제공합니다. 한 번 등록해 두면 여러 종목의 시세가 밀려 들어오는 방식이라 종목 수가 곧 호출 수가 되는 구조에서 벗어날 수 있습니다. 다만 세션당 등록 가능한 종목 수에도 제한이 있을 수 있으므로 정확한 값은 공식 문서에서 확인한 뒤 설계하세요. 연결 방식과 재접속 처리는 키움 REST API 완전 가이드에 정리돼 있습니다.

정리 — 진단 순서

증권사마다 한도 체계와 오류 규격이 다릅니다. 한국투자증권·LS증권·대신증권과의 차이는 증권사 API 비교에서, 두 증권사 API의 구조적 차이는 키움 vs KIS 비교에서 확인하실 수 있습니다. API를 쓸 때 실제로 나가는 돈은 증권사 API 수수료에 정리했습니다.

자주 묻는 질문

프로세스를 나누면 한도가 늘어나나요?

키움은 한도가 api-id 단위로 걸리므로 서로 다른 TR을 쓰는 프로세스끼리는 간섭이 적습니다. 다만 같은 TR을 두 프로세스가 동시에 부르면 그 TR의 한도는 여전히 공유됩니다. 백테스트용 수집 스크립트와 실매매 봇이 같은 시세 TR을 쓰고 있는지부터 확인해 보세요.

KIS에서 쓰던 전역 리미터를 그대로 옮겨도 되나요?

동작은 하지만 손해입니다. 전역 리미터는 모든 호출을 한 줄로 세우기 때문에, TR별로 한도가 나뉘어 있는 키움에서는 쓰지 않아도 될 여유까지 버리는 셈이 됩니다. 시세 조회가 주문을 붙잡아 체결이 늦어지는 것이 대표적인 부작용입니다.

return_code가 5가 아닌 다른 값일 때도 재시도하면 되나요?

안 됩니다. 429·return_code 5는 "속도" 문제라 시간이 해결하지만, 토큰 만료·권한·잘못된 종목코드·주문 조건 오류처럼 사람이 손대야 끝나는 오류를 재시도로 돌리면 무한 루프가 됩니다. 재시도 가능 목록을 상수로 명시해 두고 그 밖은 즉시 예외로 올리세요.

토큰을 자주 재발급받는 것도 429의 원인이 되나요?

됩니다. 토큰 발급도 호출이기 때문에 매 요청마다 새로 받으면 그 자체로 제한에 걸립니다. 접근토큰은 expires_dt 기준으로 캐싱해 만료 직전에만 갱신하는 것이 표준입니다. 만료 시각을 신뢰하지 못하겠다면 만료 60초 전 갱신 정도의 여유를 두세요.