HiAPI 속도 제한(429) 오류 해결: 원인과 해결 방법

HiAPI 게이트웨이가 HTTP 429 Too Many Requests를 반환하면, 사용 중인 API Key가 짧은 시간 안에 https://api.hiapi.ai/v1/tasks(또는 폴링 엔드포인트 GET /v1/tasks/{taskId})에서 허용된 요청 빈도나 동시성 상한을 초과했다는 뜻입니다. 응답 본문은 HiAPI의 통일된 오류 봉투({"error":{"type":"hiapi_error","code":"...","request_id":"..."}})를 따르며 429 상태 코드가 함께 옵니다. 이 문제를 해결하는 데 고객 지원에 메일을 보내야 하는 경우는 거의 없으며, 클라이언트에 아주 작은 '재시도 + 속도 제한' 로직을 한 겹 추가하면 됩니다. 이 글에서는 이 오류가 무엇인지, 왜 발생하는지, 그리고 사라지게 만드는 구체적인 단계를 설명합니다.

HiAPI 429는 어떻게 생겼나

전형적인 요청은 네트워크 계층에서 대략 이렇게 보입니다:

> POST /v1/tasks HTTP/1.1
> Host: api.hiapi.ai
> Authorization: Bearer hi-sk-...
> Content-Type: application/json

< HTTP/1.1 429 Too Many Requests
< Content-Type: application/json
<
{"error":{"type":"hiapi_error","code":"rate_limit_exceeded","request_id":"req_..."}}

두 가지 핵심:

• 상태 코드는 429이며 401/403이 아닙니다. 401은 Key가 잘못되었거나 누락되었음을 뜻하고, 429는 Key에는 문제가 없고 단지 너무 빨리 보냈다는 뜻입니다. 둘을 혼동하지 마세요.
• 응답 본문은 hiapi_error 봉투 안의 JSON입니다. 일부 HTTP 클라이언트는 기본적으로 상태 코드만 노출합니다. 코드가 로그도 남기지 않고 조용히 재시도하면 request_id 같은 디버깅 단서를 잃게 됩니다.

GPT Image 2, Nano-Banana, flux, Seedance, Wan 또는 HappyHorse 모델을 호출하는 경우, 이들은 모두 동일한 비동기 작업 엔드포인트에서 실행되므로 같은 Key 차원의 속도 계산을 공유합니다.

흔한 원인(발생 확률 순)

당사의 경험에 따르면 높은 순서에서 낮은 순서로 대략 다음과 같습니다:

1. 단일 Key의 순간 팬아웃(burst fan-out). 프롬프트 배치를 순회하면서 각각에 대해 POST /v1/tasks를 동시에 호출하고 동시성 상한도 두지 않는 경우입니다. 새 계정에서 십여 개 정도의 동시 작업 생성만으로도 상한에 도달하기에 충분합니다.
2. GET /v1/tasks/{taskId}에 대한 공격적인 폴링. while True: poll(); sleep(0.2) 같은 빡빡한 루프는 작업 생성과 똑같이 요청량으로 계산됩니다. 초 단위 미만 폴링은 '작업을 하나만 만들었는데도 429가 난다'의 최대 원인입니다.
3. 계정 수준의 동시성 상한. 무거운 모델, 즉 비디오(seedance-2.0, wan2.7-video/*, happyhorse-1.0)와 @pro 이미지 변형은 더 엄격한 동시 작업 상한에 계산됩니다. 이런 작업을 한꺼번에 많이 제출하면 분당 빈도가 높지 않아도 429가 발생합니다.
4. 하나의 Key를 여러 환경에서 공유. dev, staging, prod가 모두 같은 HIAPI_API_KEY를 사용하면 사용량이 합산됩니다. 각 환경은 개별적으로는 문제가 없지만, 합쳐지면 Key가 상한을 넘게 됩니다.
5. 요금제 할당량 소진. 무료 할당량이나 거의 다 쓴 유료 요금제는 때때로 결제 오류가 아니라 429로 나타나며, 특히 프로모션 기간에 그렇습니다.

구체적인 임계값에 관해: HiAPI의 분당 요청 수와 동시성 상한은 귀하의 계정 등급을 기준으로 합니다. 플랫폼은 고정된 수치를 공개하지 않습니다. 따라서 아래에서 제시하는 동시성 값(5, 3, 2)은 경험적 출발점일 뿐 공식 한도가 아닙니다. 대시보드의 실제 사용량을 참고하여 조정하세요.

해결 단계

순서대로 하세요. 대부분의 팀은 3단계까지만 해도 경고 알림에서 깨어나지 않게 됩니다.

1. 지터를 넣은 지수 백오프 추가

api.hiapi.ai와 통신하는 모든 클라이언트는 429를 만나면 증가하는 지연으로 재시도해야 하며, 절대 즉시 재시도해서는 안 됩니다. 안전한 기본 구현은 다음과 같습니다:

import random, time, requests

def post_task_with_backoff(body, key, *, max_retries=5):
    delay = 1.0
    for attempt in range(max_retries):
        r = requests.post(
            "https://api.hiapi.ai/v1/tasks",
            headers={"Authorization": f"Bearer {key}", "Content-Type": "application/json"},
            json=body, timeout=30,
        )
        if r.status_code != 429:
            r.raise_for_status()
            return r.json()
        retry_after = r.headers.get("Retry-After")
        wait = float(retry_after) if retry_after else delay + random.random()
        time.sleep(min(wait, 30.0))
        delay = min(delay * 2, 30.0)
    raise RuntimeError("rate-limited after retries")

이 코드는 두 가지를 올바르게 합니다. 지연을 30초로 상한을 두고, Retry-After 응답 헤더가 있으면 우선적으로 사용합니다. 이번 429 응답에 Retry-After가 없더라도 '상한 + 지터' 전략만으로 대부분의 순간 폭주를 흡수하기에 충분합니다.

2. Key별로 클라이언트 동시성 제한

클라이언트에 세마포어(semaphore)를 추가하는 것이 단일 항목으로 가장 효과적인 변경입니다. 얼마로 잡을지 모르겠다면 5부터 시작하세요:

import asyncio, httpx

sem = asyncio.Semaphore(5)

async def create_task(client, body):
    async with sem:
        r = await client.post("https://api.hiapi.ai/v1/tasks", json=body, timeout=30)
        return r.json()

동시에 5개 작업을 실행하는 것은 대부분의 계정에 여유롭습니다. 그래도 429가 나면 3으로 낮추세요. 무거운 비디오 모델은 보통 별도의 더 낮은 세마포어가 필요합니다(2를 시도해 보세요).

3. 폴링에서 callback.url로 전환

프로덕션 부하에서는 GET /v1/tasks/{taskId} 폴링이 좋은 기본값이 아닙니다. 요청 본문에 callback.url을 전달하면 HiAPI가 작업이 종료 상태에 도달했을 때 결과를 POST로 보내 줍니다:

{
  "model": "Nano-Banana",
  "input": { "prompt": "a calm lake at dawn", "aspect_ratio": "16:9" },
  "callback": { "url": "https://your-domain.com/hiapi/callback", "when": "final" }
}

이는 O(작업 수 × 폴링 횟수)의 요청 패턴을 O(작업 수)로 줄이며, 보통 10–50배의 호출량 감소이자 폴링형 429에 대한 거의 즉각적인 해결책입니다. GET /v1/tasks/{taskId}는 로컬 디버깅과 빈도가 낮은 일회성 호출에 남겨 두세요.

4. 폴링 주기를 늦추고 지터 추가

콜백을 쓸 수 없다면(오프라인 스크립트, 로컬 notebook, 대체 대사 작업) 2–5초보다 더 자주 폴링하지 말고 지터를 추가하여 여러 worker가 일제히 움직이지 않게 하세요:

import random, time
time.sleep(2 + random.random() * 3)  # 2–5 초, 지터 포함

5. 환경별로 Key 분리

HiAPI API 키 페이지에서 각 환경마다 Key를 하나씩 생성하세요. dev, staging, prod입니다. 각 환경의 순간 폭주가 서로 격리되고, 어떤 Key가 유출되더라도 다른 환경에 영향 없이 개별적으로 폐기할 수 있습니다.

6. 현재 사용량 확인

HiAPI 대시보드를 열어 동시성/요금제 상한에 부딪힌 것인지, 아니면 단지 짧은 순간 폭주였는지 확인하세요. 각 등급 요금제의 할당량은 가격 페이지에서 대조할 수 있습니다. 사용량이 요금제보다 훨씬 낮은데도 여전히 429가 난다면, 원인은 거의 확실히 계정 자체가 아니라 클라이언트 측의 순간 폭주입니다.

최소 검증

재시도 계층이 준비되면 Nano-Banana 작업 하나로 연결이 뚫려 있는지 확인하는 것이 가장 저렴한 방법입니다. $HIAPI_API_KEY를 본인의 Key로 바꾸세요:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Nano-Banana",
    "input": { "prompt": "a single red apple on a white table", "aspect_ratio": "1:1" }
  }'

성공하면 대략 이렇게 나옵니다: {"code":200,"data":{"taskId":"tk-hiapi-..."}}. 그다음 한 번 폴링하세요:

curl -s -H "Authorization: Bearer $HIAPI_API_KEY" \
  https://api.hiapi.ai/v1/tasks/tk-hiapi-...

상태는 queued → handling → archiving → success를 거치며, 최종 data.output[0].url이 바로 여러분의 이미지입니다. 이 한 번의 왕복이 200을 반환하는데도 배치 작업이 여전히 429라면, 문제는 Key가 아니라 클라이언트의 동시성에 있습니다.

자주 묻는 질문

분명히 요청을 하나만 보냈는데 왜 429가 나나요?

거의 항상 실제 요청량은 작업 생성이 아니라 폴링 루프에서 나오기 때문입니다. 동시 작업 5개에 대해 200ms 간격으로 폴링하면 그것만으로 초당 25개 요청입니다. 폴링을 2–5초로 늦추거나 callback.url로 전환하세요.

HiAPI는 반드시 Retry-After 응답 헤더를 주나요?

Retry-After는 권장값으로 취급하세요. 있으면 쓰고, 없으면 지수 백오프(1s, 2s, 4s…… 최대 30s)로 대체하세요. 어느 경우든 지연 없이 재시도하지 마세요. 그것은 순간 폭주를 더 키울 뿐입니다.

429와 401 / 403은 같은 건가요?

아닙니다. 401 / 403은 인증 실패를 뜻하며 같은 hiapi_error 봉투를 사용합니다. 예: {"error":{"code":"permission_denied","type":"hiapi_error","request_id":"req_..."}}(실측상 401의 message는 “This API key is invalid. Check that it is correct...”를 안내합니다). 401/403이 보이면 API 키 페이지에서 Key 값을 확인하세요. 백오프로는 해결되지 않습니다.

속도 상한을 바로 높일 수 있나요?

트래픽이 실제로 더 높은 동시성 상한을 필요로 한다면, 먼저 가격 페이지에서 요금제 할당량을 확인하고, 그곳에서 고객 지원에 문의하세요. 실제로 위의 해결책들은 어떠한 상한도 변경하지 않고 429 문제의 90% 이상을 해결합니다.

/v1/tasks의 429와 /v1/tasks/{taskId}의 429는 무엇이 다른가요?

엔드포인트는 당시 무엇을 하고 있었는지를 알려 줄 뿐이며, 둘은 같은 Key 차원의 속도 예산을 공유합니다. 생성 인터페이스의 429는 팬아웃(동시성 제한, 배치 처리 전환)을 가리키고, 폴링 인터페이스의 429는 빡빡한 폴링 루프(주기 늦추기 또는 콜백 전환)를 가리킵니다. 전체 요청/응답 구조는 HiAPI Quickstart와 인증 문서를 참고하세요.

요약

429는 모든 프로덕션 수준 API 게이트웨이가 내놓는 정상적이고 복구 가능한 신호입니다. 지수 백오프를 추가하고, 클라이언트 동시성을 제한하고, 폴링 대신 콜백을 사용하고, 대시보드에서 사용량을 확인하세요. 이 네 가지를 제대로 갖추고 나면 429는 더 이상 신경 쓸 일이 없어집니다. 이 페이지는 영문 원문 《How to Fix HiAPI Rate Limit (429) Errors》의 중국어 간체 버전이며, 기술적 세부 사항은 원문과 동일하게 유지됩니다.