HiAPI 작업 시간 초과 및 504 오류: 진단 및 수정 가이드

HiAPI의 작업이 GET /v1/tasks/{id}가 반환하는 응답에서 때때로 "status": "fail", "error": {"code": "TASK_TIMEOUT", "message": "Task timed out"}가 나타날 수 있습니다 — 이 응답 자체의 HTTP 상태 코드는 200이라는 점에 유의하세요. 이는 HiAPI가 문서화한 실제 실패 상태이며, 작업이 실행을 시작했지만 내부 시간 예산 안에 완료되지 못했다는 뜻입니다. 만약 이런 JSON이 아니라 클라이언트가 곧바로 순수한 HTTP 504 Gateway Timeout을 던진다면, 그것은 HiAPI의 API가 반환한 것이 전혀 아닙니다: 504는 HiAPI가 문서화한 어떤 상태 코드 목록에도 없습니다. 이 글은 이 두 상황을 나눠서 설명합니다: 진짜 TASK_TIMEOUT은 어떻게 읽고 어떻게 고치는지, 그리고 504는 대체 어디서 튀어나오는지.

오류는 실제로 어떤 모습인가

HiAPI의 작업 흐름은 비동기입니다: POST /v1/tasks가 즉시 taskId를 반환하고, 그다음 GET /v1/tasks/{id}를 폴링하여 결과를 받습니다. error 필드는 status가 종료 상태에 도달했을 때만 나타납니다. 진짜 시간 초과는 이렇게 생겼습니다:

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-xxxxxxxx",
    "model": "gpt-image-2",
    "status": "fail",
    "created": 1777282033,
    "completed": 1777282099,
    "error": { "code": "TASK_TIMEOUT", "message": "Task timed out" }
  }
}

이 응답의 HTTP 상태 코드는 200입니다 — 폴링 요청 자체는 성공했고, 실패한 것은 작업이며 실패 상세는 data.error에 있습니다. 이는 생성 단계의 동기 실패(예: 잔액 부족은 402, 요청 본문 오류는 400)와 다릅니다. 그런 오류는 최초 POST /v1/tasks 호출에서 즉시 반환되며, 이때 작업은 아직 생성조차 되지 않았습니다. TASK_TIMEOUT은 이미 성공적으로 생성된 작업에서만 발생합니다.

반면 504는 대부분의 경우 응답 본문이 아니라, 프록시, 로드 밸런서 또는 일부 HTTP 클라이언트 라이브러리가 어떤 응답이든 기다리기를 포기할 때 스스로 내뱉는 상태 코드입니다. HiAPI가 문서화한 HTTP 상태 코드는 200, 400, 402, 404, 409, 415, 422, 503이며 — 그 안에 504는 없습니다. 만약 실제로 보신 것이 401이라면 그것은 다른 문제(API Key가 유효하지 않거나 비활성화됨, 시간 초과 아님)이며 이 글의 범위가 아닙니다.

흔한 원인(발생 확률순 정렬)

1. 실제 작업 수준 시간 초과. 모델이 작업을 받았지만 내부 시간 예산 안에 완료하지 못했습니다. 바로 위에 보여드린 TASK_TIMEOUT 시나리오이며, 더 무거운 작업에서 더 흔합니다 — 더 긴 영상 길이, 더 높은 해상도, 또는 모델 자체의 일시적 과부하.
2. 504는 HiAPI 외부에서 발생. 대다수의 "504" 보고는 사실 클라이언트 자신의 read timeout(HTTP 라이브러리가 기다리지 못하고 포기), 또는 여러분과 api.hiapi.ai 사이의 회사 프록시, VPN, 로드 밸런서가 자체 시간 초과 설정에 따라 연결을 끊은 것입니다. HiAPI는 504를 결코 반환하지 않으므로, 이것은 클라이언트 또는 네트워크 측 구성 문제이지 HiAPI의 장애가 아닙니다.
3. 작업이 아직 실행 중인데 시간 초과로 오판. queued, handling, archiving은 모두 비종료 상태이며, 이때 error 필드는 존재하지 않습니다. 폴링 한 번에서 상태가 success가 아니라고 해서 시간 초과인 것은 아닙니다.

수정 단계

1. taskId로 작업을 가져와 status와 error.code를 직접 읽으세요. 클라이언트 코드의 두루뭉술한 예외 메시지로 원인을 추측하지 말고 — GET /v1/tasks/{id}를 호출해 응답 본문 자체를 확인하세요.
2. status가 "fail"이고 error.code가 "TASK_TIMEOUT"이라면: 재시도하세요. 문서화된 수정 방법은 그렇게 간단합니다 — 새로운 POST /v1/tasks 호출로 다시 제출하면 됩니다(새로운 taskId를 받습니다). 계정이나 Key를 바꿀 필요는 없습니다.
3. 작업 자체가 무겁다면 먼저 입력을 점검하세요. 더 긴 영상 길이, 더 높은 해상도, 또는 매우 방대하거나 복잡한 프롬프트는 모델을 시간 예산 상한에 더 가깝게 만듭니다. 같은 구성에서 반복적으로 시간 초과가 발생한다면 더 낮은 해상도/길이를 시도하거나 모델을 바꿔 보세요.
4. 만약 실제로 순수한 504(error.code가 담긴 JSON 응답 본문이 없는)를 보셨다면, 문제는 HiAPI 외부에 있습니다. 여러분의 HTTP 클라이언트나 SDK에 설정된 read timeout을 확인하세요 — 많은 기본값이 너무 짧으며(10-30초), 비동기 흐름에서는 애초에 긴 요청 하나를 붙잡고 있지 말고 나눠서 폴링해야 합니다. 동시에 회사 프록시, VPN 게이트웨이 또는 로드 밸런서를 거치고 있는지 확인하세요. 그것들은 자체 시간 초과 설정에 따라 HiAPI와 전혀 무관하게 연결을 끊을 수 있습니다.
5. status가 여전히 queued, handling 또는 archiving이라면 아직 재시도하지 마세요. 실제로 실패한 것은 아무것도 없습니다. 더 완전한 진단은 hiapi 작업 중단/시간 초과 진단 가이드(영어)를 참고하세요.

최소 검증 예제

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"
    }
  }'

이것은 즉시 taskId를 반환합니다:

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

그런 다음 폴링하세요:

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

정상적인 작업은 결국 "status": "success"와 출력 결과를 반환합니다. 진짜 시간 초과된 작업은 앞서 보여드린 TASK_TIMEOUT 구조를 반환합니다. 만약 연결 수준의 504를 받았고 JSON 응답 본문이 전혀 없다면, 응답이 HiAPI의 API로부터 돌아오지 못한 것이므로 — 계정에 문제가 있다고 의심하지 말고 위 단계에 따라 자신의 클라이언트 시간 초과 설정과 네트워크 경로를 점검하세요.

관련 내부 링크

• HiAPI 콘솔
• 비동기 작업 생성(API 문서)
• hiapi 작업 중단/시간 초과 진단 가이드(영어)

FAQ

HiAPI의 TASK_TIMEOUT과 HTTP 504 Gateway Timeout은 같은 것인가요? 아닙니다. TASK_TIMEOUT은 HiAPI가 문서화한 오류 코드로, 정상적인 200 응답 안에 나타나며 작업 자체의 status가 fail로 바뀌었다는 것을 의미합니다. 즉 작업이 내부적으로 시간 초과된 것입니다. 504는 일부 프록시, 로드 밸런서, HTTP 클라이언트 라이브러리가 응답 대기를 포기할 때 내는 범용 HTTP 상태 코드입니다. HiAPI의 API는 504를 문서화하지도 반환하지도 않으므로, 여러분이 본 문자 그대로의 504는 반드시 여러분과 HiAPI 사이의 어딘가, 또는 여러분 자신의 클라이언트가 대기를 포기한 것이지, HiAPI 서버의 장애가 아닙니다.

TASK_TIMEOUT을 만나면 어떻게 해야 하나요? 새 작업을 다시 제출하기만 하면 됩니다. TASK_TIMEOUT의 문서화된 수정 방법은 재시도이며, 별도의 잠금 해제 절차는 없습니다. 같은 입력에서 반복적으로 시간 초과가 나지 않는다면 프롬프트나 파라미터를 바꿀 필요도 없습니다.

시간 초과된 작업을 재시도하면 두 번 과금되나요? HiAPI가 문서화한 오류 코드 표에는 이 점이 명시되어 있지 않습니다. 이것이 중요하다면 콘솔에서 이 특정 taskId로 사용량 기록을 조회해 확인하세요. 추측으로 판단하지 마세요.

제 HTTP 클라이언트가 JSON 형식의 TASK_TIMEOUT이 아닌 시간 초과 예외를 던졌는데, 같은 것인가요? 아닙니다. 클라이언트 자신의 시간 초과(예: HTTP 라이브러리의 ReadTimeout, 또는 회사 프록시가 반환하는 504)는 여러분의 연결이 HiAPI로부터 어떤 응답이든 받기 전에 스스로 포기했다는 뜻이며, 작업 자체가 실패했다는 것을 의미하지 않습니다. /v1/tasks는 비동기이므로, 흔한 수정법은 클라이언트의 read timeout을 늘리거나(또는 아예 최초 POST에서 블로킹 대기하지 말고) GET /v1/tasks/{id}를 나눠서 폴링하며 종료 상태를 확인할 때까지 기다리는 것입니다.

작업이 이미 몇 분째 queued 또는 handling 상태인데 오류가 없습니다. 이것도 시간 초과인가요? 아직 아닙니다. queued, handling, archiving은 모두 비종료 상태이며, error 필드는 status가 fail로 바뀐 뒤에야 나타납니다. 작업이 정말로 계속 수렴하지 않는다면 hiapi 작업 중단/시간 초과 진단 가이드(영어)에서 대기열 적체 등 진행 중인 원인에 대한 전체 분석을 참고하세요.