HiAPI에서 402 잔액 부족(INSUFFICIENT_QUOTA)이 반환되면 어떻게 해야 하나요? 원인과 해결 단계

HiAPI 인터페이스를 호출할 때 간혹 HTTP 402 응답을 받게 되며, 응답 본문의 error_code가 INSUFFICIENT_QUOTA인 경우가 있습니다. 이는 계정의 Credits 잔액이 모두 소진되었음을 의미하며, API Key의 유효성, 요청 형식의 정확성, 속도 제한 여부와는 아무런 관련이 없습니다. 작업이 생성되기 전에 거부되므로 어떤 요금도 청구되지 않습니다. 해결 방법은 거의 항상 동일합니다. 충전 페이지에서 계정에 Credits를 충전한 뒤, 방금 실패한 그 요청을 그대로 다시 시도하면 됩니다.

일반적인 원인

1. 잔액이 원래 0인 경우. 신규 계정에는 가입 시 증정되는 Credits가 있으며, 이 부분과 이후 충전분을 모두 사용하고 나면 잔액이 다시 양수가 될 때까지 모든 작업 생성 호출이 402를 반환합니다.
2. 짧은 시간에 집중적으로 호출하여 잔액이 예상보다 빨리 소진되는 경우. 비디오 모델은 보통 출력 초 단위로 과금되며, 비디오 클립을 연속으로 몇 개 실행하면 소모되는 Credits가 동일한 수량의 이미지 작업보다 훨씬 많아, 미처 인지하지 못한 사이에 잔액이 바닥나기 쉽습니다.
3. 401 또는 429를 402로 오판하는 경우. HTTP 상태 코드와 error_code 필드를 직접 확인하세요. 401(error_code가 permission_denied와 유사하며 Key 자체가 유효하지 않거나 비활성화된 경우)과 429(error_code: RATE_LIMITED, 요청이 너무 빠름)는 모두 "호출 실패"처럼 보이지만, 해결 방법이 402와 완전히 다르므로 로그에서 뒤섞여 있으면 잘못된 방향으로排查하기 쉽습니다.

해결 단계

1. 먼저 잔액을 확인하세요. 콘솔의 청구 페이지를 열어 현재 Credits 잔액을 확인하세요. 이 단계에서 402가 실제로 잔액 문제 때문인지 바로 확인할 수 있습니다.
2. 계정에 충전하세요. 역시 청구 페이지에서 Credits를 추가하면 되며, 별도의 "잠금 해제" 단계는 없습니다. 잔액이 양수가 되면 작업 생성이 즉시 성공합니다.
3. 방금 했던 요청을 그대로 다시 시도하세요. 코드나 파라미터를 변경할 필요가 없습니다. 동일한 prompt, model 및 기타 필드는 잔액이 충분해지면 바로 성공합니다. 특정 모델의 단일 호출 비용이 대략 얼마인지 확실하지 않다면 먼저 가격 페이지를 확인하세요.
4. 잔액 알림을 설정하여 다음에 다시 겪지 않도록 하세요. 콘솔 설정에는 잔액 알림(Balance Alerts) 기능이 있어 잔액이 설정한 임계값보다 낮아지면 이메일로 알려주므로, 실제로 바닥나기 전에 충전할 수 있습니다.

최소 검증 예시

아래 최소 요청으로 문제가 계정 잔액에 있음을 독립적으로 확인하고, 모델이나 SDK 자체의 간섭을 배제할 수 있습니다:

curl https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "a simple test image of a red circle on a white background"
  }'

잔액이 비어 있을 때는 다음과 같은 구조가 반환됩니다:

{
  "code": 402,
  "data": null,
  "error_code": "INSUFFICIENT_QUOTA",
  "message": "insufficient account balance; top up and retry"
}

충전 후 동일한 요청으로 다시 시도하면 정상적인 작업 생성 응답으로 바뀝니다:

{
  "code": 200,
  "data": { "taskId": "tk-hiapi-xxxxxxxx" },
  "message": "success"
}

code 필드는 HTTP 상태 코드와 일치하며, error_code는 분기 판단에 사용되는 안정적인 값이고, data는 생성 실패 시 항상 null입니다.

관련 내부 링크

• HiAPI 가격
• 청구 및 잔액 관리
• 비동기 작업 생성(API 문서)

FAQ

잔액이 갑자기 바닥났는데, 이전에 아무런 안내도 없었나요? 기본적으로는 작업이 실제로 402로 실패할 때에만 잔액 부족을 알게 됩니다. 콘솔 설정에서 잔액 알림(Balance Alerts)을 켜면 잔액이 설정한 임계값보다 낮아질 때 이메일을 받게 되어 미리 충전할 수 있습니다.

402가 이미 실행 중인 작업을 중단시키나요? 아니요. INSUFFICIENT_QUOTA는 작업 생성 단계에서 반환되며, 이때 작업은 아직 존재하지 않으므로 실행 중인 작업을 중단시킨다는 것도 말이 되지 않습니다. 새 작업의 생성만 차단할 뿐입니다.

402로 실패한 요청에 요금이 청구되나요? 아니요. 잔액 확인은 작업이 실제로 생성되기 전에 이루어지며, 402는 작업이 생성되지 않았고 계정에서 어떤 Credits도 차감되지 않았음을 의미합니다.

402와 속도 제한(429)은 같은 건가요? 아니요. 속도 제한은 429를 반환하고 error_code가 RATE_LIMITED이며, 요청을 너무 빠르게 보냈다는 뜻입니다. 402는 계정의 Credits 잔액 부족을 의미하며 요청 빈도와 무관하고, 두 가지의 해결 방법도 다릅니다.

잔액이 소진되기 전에 미리 알 수 있는 방법은? 콘솔의 청구 페이지를 열면 현재 Credits 잔액과 전체 소비 내역을 볼 수 있으며, 거기서 잔액 알림 임계값을 설정할 수도 있습니다.