HiAPI 502 / 503 업스트림 오류: 원인과 해결 방법

POST https://api.hiapi.ai/v1/tasks를 호출하거나(GET /v1/tasks/{id}를 폴링하거나) 했는데, 평소처럼 200과 taskId가 반환되는 대신 502 Bad Gateway 또는 503 Service Unavailable이 반환되었습니다. 둘 다 5xx 응답으로, 문제가 서버나 전송 측에 있음을 의미하며 여러분의 요청에 문제가 있는 것은 아닙니다. 잘못된 파라미터, 잘못된 키, 형식이 잘못된 페이로드를 보낸 것이 아닙니다. 503은 HiAPI 문서에 기재된 '플랫폼 일시 사용 불가' 신호로, 재시도해야 함을 알려줍니다. 502는 경로 상의 어딘가에서 생성된 게이트웨이 수준의 응답입니다. 본 가이드는 이를 어떻게 확인할지, 중복 작업 없이 안전하게 재시도하는 방법, 그리고 502/503을 504 타임아웃 및 TASK_FAILED 결과와 구분하는 방법을 설명합니다.

502 또는 503은 실제로 어떤 모습인가

정상적인 200 대신 HTTP 상태 줄에 다음 중 하나가 표시됩니다:

• 503 Service Unavailable —— 이는 문서화되어 있습니다. HiAPI의 비동기 API 문서는 503을 "플랫폼 일시 사용 불가; 잠시 후 지수 백오프로 재시도하십시오"로 명시하며, 해당 비즈니스 코드는 TEMPORARILY_UNAVAILABLE("생성 서비스가 일시적으로 사용 불가합니다. 잠시 후 재시도하십시오. 문제가 지속되면 지원팀에 문의하십시오.")입니다. HiAPI의 동기 오류는 플랫 JSON 봉투를 사용합니다. 문서에서 400의 경우는 {"code": 400, "message": "...", "data": null, "error_code": "INVALID_REQUEST"}이며, 따라서 API가 반환하는 503도 동일한 봉투에 error_code: "TEMPORARILY_UNAVAILABLE"을 담아야 합니다.
• 502 Bad Gateway —— 이는 HiAPI 문서에 기재된 상태 코드가 아닙니다. 표준 HTTP에서 502는 게이트웨이나 프록시가 접근하려는 다음 홉으로부터 유효하지 않거나 빈 응답을 받았음을 의미합니다. 따라서 여러분이 받은 502는 경로 상의 게이트웨이, 즉 엣지/CDN 계층, 로드 밸런서, 또는 여러분 네트워크의 프록시에서 생성된 것이며, HiAPI 애플리케이션이 평소의 JSON 봉투를 반환한 것이 아닙니다. 응답 본문은 보통 짧은 HTML 또는 일반 텍스트 게이트웨이 페이지이며, 이 비-JSON 본문 자체가 신호입니다. 즉, 고정되고 문서화된 페이로드를 가진 애플리케이션 오류가 아니라 전송/게이트웨이 상황임을 나타냅니다.

어느 경우든 상태는 5xx입니다. 문제는 서버나 전송 측에 있으며, 여러분의 요청에는 없습니다. 이는 4xx와 반대입니다. 400(파라미터 오류), 401(키 오류; HiAPI는 중첩된 {"error": {"code": "permission_denied", "type": "hiapi_error", "request_id": "..."}}를 반환함) 또는 402(잔액 부족)는 여러분 쪽에서 무언가를 변경해야 해결됩니다. 502/503은 페이로드를 수정해서 해결할 수 없습니다.

일반적인 원인(가능성이 높은 순서대로)

1. 일시적인 플랫폼 과부하 또는 유지보수 시간 → 503 TEMPORARILY_UNAVAILABLE. 이는 예상된, 문서화된 상황입니다. 스스로 복구되며, 백오프 재시도로 성공합니다.
2. 경로 상의 게이트웨이나 프록시의 순간적인 흔들림 → 502. 엣지/CDN 계층, 로드 밸런서, 또는 여러분 네트워크의 프록시가 잠시 응답을 전달하지 못했습니다. 역시 일시적입니다.
3. 트래픽 급증이 제한을 유발함. 높은 부하에서는 오히려 429 RATE_LIMITED("잠시 후 재시도하십시오. 동일한 요청을 즉시 다시 제출하지 마십시오")가 표시될 수 있습니다. 상태가 429라면 해결책은 더 강하게 재시도하는 것이 아니라 전송 속도를 낮추는 것입니다.
4. 요청한 모델 백엔드가 일시적으로 사용 불가. HiAPI는 이를 작업 수준에서 MODEL_UNAVAILABLE("잠시 후 재시도하거나 모델을 전환하십시오")로 기록합니다. 해당 모델을 서비스하는 플랫폼 수준의 일시적 장애도 503으로 나타날 수 있습니다.
5. 아닙니다: 키 오류, 요청 본문 형식 오류, 잔액 부족은 아닙니다. 이들은 각각 401 / 400 / 402이며, 502나 503으로 나타나지 않습니다.

순서대로 해결하는 방법

1. 5xx인지 4xx인지 확인하십시오. 먼저 상태 코드를 보십시오. 502/503은 서버/전송 측에 속합니다. 400, 401, 402, 404, 409, 415, 422, 429는 여러분 측에 속합니다. 정말 502/503이라면 요청 본문을 다시 작성하지 마십시오. 그것은 4xx에만 도움이 됩니다.
2. 지터를 포함한 지수 백오프로 재시도하십시오. 문서는 503에 대해 지수 백오프를 명확히 요구합니다. 안전한 클라이언트 패턴은 약 1초로 시작해 시도마다 두 배로 늘리고(2초, 4초, 8초……), 약 30–60초를 상한으로 하며, 다수의 클라이언트가 동시에 재시도하지 않도록 무작위 지터를 추가하는 것입니다. 이 간격은 권장 클라이언트 패턴이며, HiAPI가 발표한 시간 보장은 아닙니다.
3. 제출을 멱등하게 만드십시오. POST /v1/tasks에 Idempotency-Key 헤더를 설정하십시오(임의의 UTF-8 문자열, 최대 255바이트). 502/503으로 인해 작업이 실제로 생성되었는지 확실하지 않다면, 동일한 키로 재시도하는 것이 안전합니다. 동일한 키 + 동일한 요청 본문은 원래의 taskId를 응답 헤더 Idempotent-Replay: true와 함께 반환하며, 두 번째 작업을 생성하거나 두 번째 과금을 발생시키지 않습니다. 키는 계정 범위로 제한되며 24시간 후 만료됩니다. 전체 규약은 Unified Async API 문서를 참조하십시오.
4. 키 없이 무작정 다시 POST하지 마십시오. Idempotency-Key 없이 제출했는데 502/503을 받았다면, 보이지 않는 작업이 이미 생성되었을 수 있습니다. 폴링할 taskId가 없으므로 순진한 재시도는 중복 작업과 중복 과금의 위험이 있습니다. 어떤 규모로든 재시도하기 전에 키를 추가하십시오.
5. 폴링 중에 502/503이 발생하면 계속 폴링하면 됩니다. GET /v1/tasks/{id}가 반환하는 5xx는 작업 상태를 변경하지 않습니다. 종료 상태(success / fail)는 도달하면 고정되며 서로 전환되지 않으므로, 백오프 후 다시 폴링하면 됩니다. 또는 callback.url을 등록하여 종료 상태 시 알림을 받아 일시적인 5xx를 통과하며 폴링할 필요가 없게 하십시오. 전달은 최소 한 번이므로 taskId로 중복 제거하십시오.
6. 작업 수준 실패와 구분하십시오. 대신 HTTP 200과 "status": "fail"을 받았다면 그것은 502/503이 아닙니다. 작업은 접수되고 실행된 후 실패한 것입니다. 게이트웨이 재시도를 무작정 하지 말고 TASK_FAILED("한 번 재시도하십시오. 문제가 지속되면 지원팀에 문의하십시오") 또는 TASK_TIMEOUT("해당 작업을 재시도하십시오")을 각각의 방식으로 처리하십시오.
7. 지속되면 두드리지 말고 에스컬레이션하십시오. 502/503이 몇 분 동안 여러 차례 백오프 재시도 후에도 계속 발생하면, 무력으로 해결할 문제가 아니라 일시적인 플랫폼 이벤트로 간주하십시오. 공격적인 재시도를 중단하고 오류 본문에 request_id가 포함되어 있으면 이를 함께 지원팀에 문의하십시오. HiAPI 콘솔에서 계정과 연결 상태가 정상인지 확인할 수 있습니다.

502 / 503과 504와 TASK_FAILED 비교

모두 '깔끔하게 반환되지 않았다'는 의미라 혼동하기 쉽지만, 처리 방식은 다릅니다:

응답	HTTP 상태 코드	출처	작업이 과금되었는가?	해야 할 일
503 Service Unavailable	503(문서화됨)	HiAPI 플랫폼 —— 일시 사용 불가 또는 과부하	응답으로 판단 불가; 작업이 이미 존재할 수 있음	백오프와 동일한 Idempotency-Key로 재시도
502 Bad Gateway	502(HiAPI 문서에 없음)	경로 상의 게이트웨이/프록시(엣지, 로드 밸런서 또는 여러분의 프록시)	응답으로 판단 불가	백오프로 멱등 재시도; 여러분 네트워크에서만 발생하면 여러분 측 프록시를 의심
504 Gateway Timeout	504(HiAPI 문서에 없음)	대기를 멈춘 경로 상의 게이트웨이 또는 프록시(HiAPI 문서는 504를 나열하지 않음)	응답으로 판단 불가	502와 동일; HiAPI는 자체 타임아웃을 TASK_TIMEOUT으로 보고
TASK_TIMEOUT	200 + "status": "fail"	HiAPI —— 작업이 실행되었지만 시간 예산 초과	아니요(예약 금액 환불됨)	해당 작업을 새 요청으로 재시도
TASK_FAILED	200 + "status": "fail"	HiAPI —— 작업이 접수되어 실행된 후 실패	아니요(예약 금액 환불됨)	한 번 재시도한 후 error.message 읽기
429 RATE_LIMITED	429	HiAPI —— 너무 빠르게 전송함	작업 없음	백오프; 즉시 다시 제출하지 말 것
400 / 401 / 402	4xx	HiAPI —— 클라이언트 측(요청 본문/키/잔액 오류)	아니요	요청, 키 또는 잔액을 수정; 재시도는 도움이 되지 않음

한 문장으로 판단하면: 502/503/504는 HTTP 전송 오류이며 어떤 작업 결과도 담지 않습니다. 반면 TASK_FAILED / TASK_TIMEOUT은 HTTP 200과 "status": "fail" 및 error 객체의 형태로 도달합니다. 전자는 '요청이 전달되었는지 알 수 없다'는 의미이고, 후자는 '요청이 전달되었고 작업이 실행되었으며 실패했다'는 의미입니다.

최소 검증 예제

깨끗한 제출 한 번으로 키와 연결 상태가 정상임을 증명하고 502/503을 일시적 문제로 격리하십시오. 확실히 사용 가능한 모델 id(예: gpt-image-2/text-to-image)를 사용하고 재시도가 안전하도록 Idempotency-Key를 포함하십시오:

# A healthy submit returns 200 with a taskId. If this works but a specific
# call just 502/503'd, that 502/503 was transient — not your setup.
curl -sS -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-job-0001" \
  -d '{"model":"gpt-image-2/text-to-image","input":{"prompt":"a red bicycle on a white background"}}'

# Then poll the task you just created (swap in the returned id):
curl -sS https://api.hiapi.ai/v1/tasks/TASK_ID \
  -H "Authorization: Bearer $HIAPI_API_KEY"

제출 자체가 200과 taskId를 반환하면 인증과 네트워크 경로가 정상이며, 이전의 502/503은 일시적인 서버/전송 상황이었습니다. 실패한 호출을 재시도하십시오(동일한 Idempotency-Key를 재사용하면 중복 작업이 아닌 원래 작업이 반환됨). 반대로 제출이 401 또는 400을 반환하면 이는 502/503이 아니라 클라이언트 측 문제입니다.

관련 읽기

• HiAPI 작업 타임아웃과 504 오류: 해결 방법 —— 원시 504가 HiAPI에서 오지 않는 이유와 TASK_TIMEOUT의 의미.
• HiAPI TASK_FAILED 오류: 원인과 해결 방법 —— 200 + "status": "fail"을 반환하는 작업 처리.
• hiapi /v1/tasks 작업이 멈추거나 타임아웃될 때: 진단과 재시도 —— 폴링 간격과 재시도 전략에 대한 심층 안내.
• HiAPI 속도 제한(429) 오류 해결 방법 —— 실제 문제가 가용성이 아니라 전송 속도일 때.
• 실패한 HiAPI 요청이 왜 과금되는가? —— 실패한 작업의 예약과 환불이 어떻게 작동하는지.

자주 묻는 질문

502나 503은 제 잘못인가요? 아닙니다. 둘 다 5xx 응답으로 서버 측 또는 전송 측에 속합니다. 여러분의 API 키와 요청 본문은 원인이 아닙니다. 4xx(400/401/402)가 여러분이 유발하고 수정할 수 있는 부류입니다. 502/503에 대한 올바른 대응은 코드를 바꾸는 것이 아니라 멱등 재시도입니다.

HiAPI에서 502와 503의 차이는 무엇인가요? 503은 HiAPI 문서에 기재된 '플랫폼 일시 사용 불가' 코드(error_code: TEMPORARILY_UNAVAILABLE)이며 플랫폼 자체에서 발생합니다. 502는 HiAPI 문서에 기재된 상태 코드가 아닙니다. 표준 HTTP에서 502는 업스트림이 유효하지 않은 응답을 반환할 때 경로 상의 게이트웨이나 프록시가 발행합니다. 둘 다 일시적이며 백오프 재시도가 필요하지만, 502는 여러분 네트워크의 프록시를 가리킬 수도 있습니다.

503과 504는 어떻게 다른가요? 503은 서비스가 현재 일시적으로 사용 불가하거나 과부하임을 의미합니다. 504 Gateway Timeout은 어딘가에서 응답을 너무 오래 기다렸음을 의미합니다. HiAPI 문서는 504를 나열하지 않습니다. 이를 본다면 경로 상의 게이트웨이나 프록시가 대기를 포기했다는 뜻입니다. HiAPI 자체의 '시간 초과' 상태는 작업 결과 TASK_TIMEOUT(HTTP 200 + "status": "fail")입니다. 위의 504 가이드를 참조하십시오.

502/503과 TASK_FAILED 결과를 어떻게 구분하나요? HTTP 상태 코드를 보십시오. 502/503은 작업 페이로드가 없는 HTTP 오류입니다. TASK_FAILED는 HTTP 200과 "status": "fail" 및 error 객체의 형태로 반환됩니다. 작업이 접수되어 실행된 것입니다. 502/503에는 백오프 재시도를 사용하고, TASK_FAILED에는 한 번 재시도한 후 error.message를 읽으십시오.

502/503 후 재시도하면 두 번 과금되거나 중복 작업이 생성되나요? POST /v1/tasks에 Idempotency-Key 헤더를 보내면 그렇지 않습니다. 동일한 키 + 요청 본문을 재사용하면 중복 작업을 생성하지 않고 원래의 taskId(Idempotent-Replay: true)를 반환합니다. 또한 실패한 작업은 과금되지 않습니다. 작업이 실패 종료 상태에 도달하면 생성 시 예약된 금액이 전액 환불됩니다.

얼마나 백오프해야 하며, 언제 에스컬레이션해야 하나요? 지터를 포함한 지수 백오프(예: 1초, 2초, 4초, 8초, 상한 설정, 무작위성 추가)를 사용하십시오. 502/503이 몇 분 동안 여러 차례 재시도 후에도 계속 반환되면 공격적인 재시도를 중단하고 오류 본문의 request_id를 함께 지원팀에 문의하십시오. 지속적인 5xx는 보통 더 빠른 재시도 루프로 해결할 수 있는 문제가 아니라 일시적인 플랫폼 이벤트를 의미합니다.

502/503을 보았을 때 요청 페이로드를 수정해야 하나요? 아니요. 502/503은 검증 오류가 아니므로 파라미터를 수정해도 도움이 되지 않으며, 실제 일시적 원인을 가릴 수 있습니다. 요청을 그대로 유지하고 아직 추가하지 않았다면 Idempotency-Key를 추가한 후 백오프로 재시도하십시오.