튜토리얼

hiapi /v1/tasks 작업이 멈추거나 타임아웃될 때: 진단 절차와 재시도 전략

Oct 13, 2026

POST https://api.hiapi.ai/v1/tasks로 작업을 제출하고 taskId를 받았는데, GET /v1/tasks/{taskId}로 조회해 보면 data.status가 몇 분째 queued 또는 handling에 머물러 "멈춘" 것처럼 보이거나, 폴링 루프가 직접 설정한 상한에 도달할 때까지 종료 상태에 이르지 못해 타임아웃이 발생할 수 있습니다. 먼저 재제출부터 서두르지 마세요. hiapi의 작업은 비동기이므로 "아직 끝나지 않음"과 "이미 실패함"은 전혀 다른 문제입니다. 진단을 명확히 한 뒤에 움직여야 고치다가 더 나빠지는 일을 피할 수 있습니다.

data.status가 이미 fail이고 error.code가 TASK_TIMEOUT이거나, 브라우저/프록시가 문자 그대로 HTTP 504를 반환한다면 그것은 다른 종류의 문제입니다(작업이 실제로 실패했거나, 타임아웃이 당신과 hiapi 사이의 네트워크 계층에서 발생한 경우). 이 경우 HiAPI 작업 타임아웃과 504 오류 트러블슈팅을 참고하세요. 이 글은 작업이 좀처럼 종료 상태에 도달하지 못하는 "멈춤" 상황만 다룹니다.

문제 증상

"멈춘" 작업을 조회하면 대략 다음과 같은 응답이 돌아옵니다(HTTP 200이지만 작업은 아직 비종료 상태).

{
  "data": {
    "taskId": "…",
    "status": "queued",
    "output": null,
    "error": null
  }
}

핵심 특징은 data.status가 queued(대기 중) / handling(처리 중) / archiving(보관 중) 중 하나이고, data.error가 null이며, data.output에는 아직 내용이 없다는 점입니다. 이는 작업이 정상이며 단지 아직 끝나지 않았음을 의미합니다.

hiapi 작업의 종료 상태는 단 두 가지입니다. data.status가 success 또는 fail인 경우입니다. 이 둘이 아니라면 작업이 끝나지 않은 것이며, "멈춤"은 거의 항상 이 비종료 상태 구간에서 발생합니다.

혼동하기 쉬운 두 가지 "가짜 멈춤"이 있습니다.

조회가 404를 직접 반환하는 경우:
```
{"code": 404, "data": null, "message": "task not found"}
```
이것은 멈춤이 아니라 taskId를 잘못 적었거나, 작업이 아예 생성되지 않았거나, 작업 레코드가 만료된 경우입니다. 제출할 때 받은 data.taskId를 확인하세요.
제출 시점에 동기적으로 거부된 경우(taskId를 아예 받지 못함). 예를 들어 model을 잘못 적은 경우입니다.
```
{"code": 400, "data": null, "error_code": "MODEL_UNAVAILABLE", "message": "model not available via /v1/tasks"}
```
이런 경우는 요청 자체의 문제이지 작업이 멈춘 것이 아니므로, 올바르게 수정해서 다시 제출하면 됩니다.

흔한 원인(발생 확률 순)

1. 큐 적체(가장 흔함)

특정 모델(이미지 모델, 비디오 모델 또는 연산량이 많은 모델)이 대량으로 호출되고 있으면, 당신의 작업은 해당 모델의 큐에서 worker가 가져가기를 기다립니다.

신호: data.status가 queued이고 data.error가 null이며, 제출 시각으로부터 얼마 지나지 않았음.
해결: 폴링 간격을 늦추세요. 5–10초에 한 번이면 충분하며, 100ms로 공회전하지 마세요. 대부분의 작업은 1~2분 안에 가져가집니다.

2. 무거운 모델은 원래 오래 걸림

작업은 이미 가져가졌지만(handling/archiving), 이 모델은 한 번 완료하는 데 원래 오래 걸립니다. 긴 비디오, 높은 해상도, 여러 참조 이미지는 소요 시간을 크게 늘립니다.

신호: data.status가 handling 또는 archiving이며, 몇 분간 지속되지만 오류는 없음.
해결: 무거운 작업에는 폴링 상한을 더 넉넉하게 두세요(모델 성능에 맞게 여유를 충분히). 오래 걸리는 것 ≠ 실패이므로, 결과가 나오기 직전에 스스로 끊지 마세요.

3. 폴링 방식이 잘못됨("멈춤"으로 오판하기 가장 쉬움)

많은 "멈춤"은 사실 클라이언트 문제입니다. 폴링 간격이 너무 짧아 스스로 혼란을 겪거나, 상한을 두지 않았거나, 상한이 너무 짧아 너무 일찍 포기하는 경우입니다.

신호: 서버의 data.status는 계속 정상적으로 진행되지만, 당신의 루프가 일찍 타임아웃을 던지거나, data.status를 아예 읽지 않고 있음.
해결: 고정 간격(권장 5초) + 합리적인 상한(일반 작업 약 10분, 무거운 작업은 더 길게)을 사용하세요. 타임아웃은 당신의 루프가 판정해야 하며, 서버의 timeout 상태를 기대해서는 안 됩니다. hiapi에는 그런 상태가 없습니다.

4. 콜백 엔드포인트에 도달 불가

작업 제출 시 콜백(callback)을 지정했다면, 작업 자체는 이미 success일 수 있지만 결과가 당신 쪽으로 전달되지 않아 "아무 움직임이 없는" 것처럼 보일 수 있습니다.

신호: 직접 조회한 data.status는 이미 success이고 data.output에 내용이 있지만, 콜백 엔드포인트에는 아무것도 수신되지 않음.
해결: 콜백 주소는 공인망에서 접근 가능해야 하고, POST를 받을 수 있어야 하며, 약 10초 이내에 2xx를 반환해야 합니다. 그렇지 않다면 폴링으로 전환하세요. 자세한 내용은 hiapi 작업 콜백이 발생하지 않는 이유를 참고하세요.

해결 단계

먼저 상태를 한 번 조회하고, 감으로 재제출하지 마세요: GET /v1/tasks/{taskId}로 data.status와 data.error를 읽으세요.
상태별로 분기:
- queued / handling / archiving → 아직 실행 중이므로 5–10초 후 다시 조회(원인 1 / 2).
- success → 작업 성공, data.output에서 결과를 가져오세요. 콜백을 기다렸는데 받지 못했다면 → 원인 4.
- fail → data.error.code와 data.error.message를 읽으세요. TASK_TIMEOUT이면 → 타임아웃과 504 가이드를 보세요.
- 404 task not found → taskId가 틀렸거나 생성되지 않은 것이므로, 제출 응답의 data.taskId를 다시 확인하세요.
output에는 유효 기간이 있음: data.output의 다운로드 URL에는 expireAt(약 7일)이 붙으므로, 받은 즉시 디스크에 저장하거나 다른 곳으로 옮기세요. 핫링크를 장기 보관하지 마세요.
인증 / 요청 문제가 아님을 확인: 아래 최소 검증 예제를 실행해 key와 model id 문제를 배제하세요.
정말 재시도해야 한다면 백오프 사용: 다음 섹션의 재시도 전략을 참고하고, 타이트한 루프 안에서 같은 body를 반복 재제출하지 마세요.

최소 검증 예제

최소 요청으로 key와 작업 API 자체가 정상 동작하는지 확인하세요. model은 생 id(예: gpt-image-2)를 사용합니다.

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "input": { "prompt": "a single red apple on a white background, studio lighting" }
  }'

제출에 성공하면 {"data":{"taskId":"…","status":"queued"}}와 비슷한 응답을 받습니다. taskId로 폴링하세요.

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

401이 반환되고 body가 {"error":{"code":"permission_denied","type":"hiapi_error","request_id":"…"}}라면 문제는 작업이 아니라 key에 있습니다. 먼저 API Key 무효 오류 트러블슈팅을 보세요.
제출이 400 + "error_code":"MODEL_UNAVAILABLE"로 거부된다면 model id 문제입니다. 생 id를 전달하고 hiapi "모델 사용 불가" 오류와 대조하세요.

고치다 더 나빠지지 않는 재시도 전략

지수 백오프: 5s → 15s → 45s를 권장합니다.
최대 3회: 세 번째에도 실패하면 에스컬레이션하세요(모델 변경, 설정 하향, 또는 티켓 생성). 무한 루프에 빠지지 마세요.
재시도할 때마다 새 작업: POST /v1/tasks 한 번이 곧 새로운 taskId이며, 새로운 과금이 발생할 수 있습니다. hiapi는 대외적으로 약속한 "멱등 재제출"이 없으므로, 같은 body를 재제출해도 기존 작업이 재사용되리라 기대하지 마세요.
429를 만나면 늦춰야 할 것은 제출 속도이지 폴링 속도가 아닙니다: hiapi 속도 제한(429) 오류 해결 방법을 참고하세요.

안정적인 Python 폴링 + 백오프 예제:

import time, os, requests

BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}

def submit_and_wait(body, poll_interval=5, max_wait=600):
    r = requests.post(BASE, json=body, headers=HEADERS, timeout=30)
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]

    deadline = time.time() + max_wait
    while time.time() < deadline:
        time.sleep(poll_interval)
        data = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30).json()
        status = (data.get("data") or {}).get("status")
        if status == "success":
            return data["data"]["output"]
        if status == "fail":
            raise RuntimeError(data["data"].get("error"))
        # queued / handling / archiving → 계속 대기
    raise TimeoutError(f"task {task_id} 가 {max_wait}s 내에 종료 상태에 도달하지 않음")

종료 상태 판정은 success와 fail만 인정한다는 점에 주의하세요. 나머지 상태(queued / handling / archiving)는 모두 계속 대기하며, 타임아웃은 당신의 max_wait가 결정합니다.

언제 에스컬레이션해야 할까

백오프를 포함해 3회 재시도했는데 매번 같은 data.error.code → 일시적 흔들림이 아니므로 입력을 바꾸거나 모델을 교체하세요.
작업이 오랫동안 queued에 머물며 전혀 진행되지 않음 → hiapi 콘솔에서 플랫폼 공지가 있는지 확인하고, request_id를 포함해 티켓을 생성하세요.
data.status가 이미 success인데 콜백이 계속 오지 않음 → 해당 엔드포인트는 콜백에 의존하지 말고 폴링으로 바꾸세요.

FAQ

Q: 얼마나 지나야 "타임아웃"인가요? 통일된 타임아웃 시간이 있나요? A: 통일된 숫자는 없으며 모델에 따라 다릅니다. 무거운 작업(긴 비디오, 높은 해상도)은 더 오래 걸립니다. 또한 hiapi에는 서버 측 timeout 상태가 없습니다. 소위 타임아웃은 대개 당신의 폴링 루프가 스스로 설정한 상한에 도달한 것입니다. 서버에서 실제로 타임아웃으로 실패한 작업은 data.status:"fail" + error.code:"TASK_TIMEOUT"이 되며, 그 경우는 타임아웃과 504 가이드를 보세요.

Q: 작업이 queued된 지 30초가 지났는데, 취소하고 재시도해야 하나요? A: 아닙니다. 30초는 어떤 비자명한 모델에도 정상 범위이므로, 최소 2분은 기다린 뒤 재시도를 고려하세요.

Q: 실행 중인 작업을 취소할 수 있나요? A: 일반적으로 취소를 지원하지 않습니다. 설령 취소할 수 있더라도 큐 / 연산 슬롯은 보통 이미 점유된 상태입니다. 그냥 끝까지 실행하게 두고 결과를 조회하는 편이 더 이득입니다.

Q: 어제는 되던 같은 요청이 오늘은 멈추나요? A: 대부분 모델 계층의 큐 적체(원인 1)입니다. 성능이 비슷한 다른 모델로 바꾸거나, 큐가 줄어들 때까지 5–10분 기다린 뒤 다시 시도하세요.

Q: 모든 작업이 타임아웃되는데, 제 계정 문제인가요? A: 먼저 hiapi 콘솔에서 계정 수준 공지가 있는지 확인하고, 속도 제한에 걸렸는지 확인하세요(429 가이드 참고). 모두 정상이고 특정 모델 하나만 실패한다면, 십중팔구 그 모델의 큐나 백엔드 문제이지 당신의 계정 문제가 아닙니다.

Q: 멈추거나 타임아웃된 작업을 재시도하면 과금이 중복되나요? A: POST /v1/tasks를 할 때마다 새로운 과금 작업이 됩니다. 결과물을 내지 못한 실패 작업은 보통 산출 과금이 부과되지 않지만, 큐 / 연산 슬롯은 이미 점유되었을 수 있습니다. 비용이 신경 쓰인다면 나중에 사용량 페이지에서 확인하세요.