Erro upstream 502 / 503 do HiAPI: causas e como corrigir

Você chama POST https://api.hiapi.ai/v1/tasks (ou faz polling em GET /v1/tasks/{id}) e, em vez do habitual 200 com taskId, recebe 502 Bad Gateway ou 503 Service Unavailable. Ambos são respostas 5xx, o que significa que o problema está no servidor ou no lado da transmissão, não na sua requisição: você não enviou parâmetros errados, chave errada nem payload malformado. O 503 é o sinal de "plataforma temporariamente indisponível" documentado na documentação do HiAPI, que indica que você deve tentar novamente; já o 502 é uma resposta em nível de gateway gerada em algum ponto do caminho. Este guia explica como confirmar isso, como tentar novamente com segurança sem retrabalho e como distinguir 502/503 de timeouts 504 e de resultados TASK_FAILED.

Como um 502 ou 503 se parece na prática

Você verá uma das seguintes linhas de status HTTP em vez do normal 200:

• 503 Service Unavailable —— este é documentado. A documentação da API assíncrona do HiAPI lista o 503 como "plataforma temporariamente indisponível; tente novamente mais tarde com backoff exponencial", com o código de negócio correspondente TEMPORARILY_UNAVAILABLE ("Serviço de geração temporariamente indisponível. Tente novamente mais tarde; se o problema persistir, entre em contato com o suporte."). Os erros síncronos do HiAPI usam um envelope JSON plano — o caso 400 documentado é {"code": 400, "message": "...", "data": null, "error_code": "INVALID_REQUEST"} — portanto um 503 retornado pela API também deve usar o mesmo envelope, com error_code: "TEMPORARILY_UNAVAILABLE".
• 502 Bad Gateway —— este não está entre os códigos de status documentados do HiAPI. No HTTP padrão, 502 significa que um gateway ou proxy recebeu uma resposta inválida ou vazia do próximo salto que tentou acessar. Portanto, o 502 que você recebe é gerado por um gateway no caminho — possivelmente a camada de borda/CDN, o balanceador de carga ou um proxy na sua própria rede — e não pelo aplicativo HiAPI retornando seu envelope JSON habitual. O corpo da resposta costuma ser uma página curta de gateway em HTML ou texto puro, e esse corpo não-JSON é, por si só, um sinal: indica uma condição de transmissão/gateway, e não um erro de aplicação com payload fixo e documentado.

Em ambos os casos, o status é 5xx: o problema está no servidor ou no lado da transmissão, não na sua requisição. Isso é o oposto de 4xx — 400 (parâmetro inválido), 401 (chave inválida; o HiAPI retorna o envelope aninhado {"error": {"code": "permission_denied", "type": "hiapi_error", "request_id": "..."}}) ou 402 (saldo insuficiente) — que exigem que você altere algo do seu lado para corrigir. 502/503 não podem ser corrigidos modificando o payload.

Causas comuns (da mais provável para a menos provável)

1. Sobrecarga temporária da plataforma ou janela de manutenção → 503 TEMPORARILY_UNAVAILABLE. Esta é uma situação esperada e documentada. Ela se resolve sozinha, e uma nova tentativa com backoff terá sucesso.
2. Oscilação momentânea de algum gateway ou proxy no caminho → 502. A camada de borda/CDN, o balanceador de carga ou um proxy na sua própria rede falhou brevemente ao encaminhar a resposta. Também é temporário.
3. Pico de tráfego acionou uma limitação. Sob alta carga, você pode, em vez disso, ver 429 RATE_LIMITED ("Tente novamente mais tarde; evite reenviar a mesma requisição imediatamente"). Se o status for 429, a solução é reduzir a taxa de envio, e não tentar novamente com mais força.
4. O backend do modelo solicitado está temporariamente indisponível. O HiAPI registra isso no nível da tarefa como MODEL_UNAVAILABLE ("Tente novamente mais tarde ou troque de modelo"); uma falha breve em nível de plataforma no serviço que atende esse modelo também pode se manifestar como 503.
5. Não é erro de chave, corpo de requisição malformado nem saldo insuficiente. Esses são 401 / 400 / 402, respectivamente, e nenhum deles se manifesta como 502 ou 503.

Como corrigir, em ordem

1. Confirme que é 5xx e não 4xx. Verifique primeiro o código de status. 502/503 são do lado do servidor/transmissão; 400, 401, 402, 404, 409, 415, 422 e 429 são do seu lado. Se for realmente 502/503, não comece a reescrever o corpo da requisição — isso só ajuda em 4xx.
2. Tente novamente com backoff exponencial e jitter. A documentação exige explicitamente backoff exponencial para 503. O padrão seguro no cliente é começar em cerca de 1 segundo, dobrando a cada tentativa (2 s, 4 s, 8 s…), com teto em torno de 30–60 segundos, e adicionar jitter aleatório para evitar que muitos clientes tentem novamente em sincronia. Esses intervalos são padrões recomendados para o cliente, não garantias de tempo publicadas pelo HiAPI.
3. Torne o envio idempotente. Defina o cabeçalho Idempotency-Key no POST /v1/tasks (qualquer string UTF-8, com até 255 bytes). Se o 502/503 deixar você em dúvida se a tarefa foi realmente criada, repetir com a mesma chave é seguro: a mesma chave + o mesmo corpo de requisição retornarão o taskId original, com o cabeçalho de resposta Idempotent-Replay: true, sem criar uma segunda tarefa nem gerar uma segunda cobrança. A chave tem escopo por conta e expira após 24 horas. A convenção completa está na documentação do Unified Async API.
4. Não faça POST novamente às cegas sem a chave. Se você enviou sem Idempotency-Key e recebeu 502/503, pode ter criado uma tarefa que você não consegue ver — você não tem um taskId para consultar via polling, então uma nova tentativa ingênua corre o risco de retrabalho e cobrança duplicada. Adicione a chave antes de tentar novamente em qualquer escala.
5. Se o 502/503 ocorrer durante o polling, basta continuar o polling. Um 5xx retornado por GET /v1/tasks/{id} não altera o estado da tarefa. Os estados terminais (success / fail) são fixos assim que alcançados e nunca mudam de um para o outro, então basta consultar novamente após o backoff. Alternativamente, registre callback.url para ser notificado no estado terminal, sem precisar atravessar 5xx temporários no polling — a entrega é pelo menos uma vez, portanto deduplique pelo taskId.
6. Distinga isso de falhas no nível da tarefa. Se você receber um HTTP 200 com "status": "fail", isso não é 502/503 — a tarefa foi aceita, executada e falhou. Trate esse caso como TASK_FAILED ("Tente novamente uma vez; se o problema persistir, entre em contato com o suporte") ou TASK_TIMEOUT ("Tente novamente essa tarefa") conforme o caso, em vez de fazer novas tentativas cegas de gateway.
7. Se persistir, escale em vez de insistir. Se o 502/503 continuar aparecendo após várias tentativas com backoff ao longo de alguns minutos, trate isso como um incidente temporário da plataforma, e não como algo a ser resolvido na força bruta. Pare as novas tentativas agressivas e entre em contato com o suporte incluindo o request_id quando o corpo do erro o contiver. Você pode verificar se sua conta e conectividade estão normais no console do HiAPI.

502 / 503 versus 504 versus TASK_FAILED

É fácil confundir esses casos, porque todos significam "não retornou de forma limpa", mas exigem tratamentos diferentes:

Resposta	Código de status HTTP	Origem	A tarefa foi cobrada?	O que fazer
503 Service Unavailable	503 (documentado)	Plataforma HiAPI — temporariamente indisponível ou sobrecarregada	Não dá para saber pela resposta; a tarefa pode já existir	Tente novamente com backoff e o mesmo Idempotency-Key
502 Bad Gateway	502 (não está na documentação do HiAPI)	Gateway/proxy no caminho (borda, balanceador de carga ou seu próprio proxy)	Não dá para saber pela resposta	Faça nova tentativa idempotente com backoff; se ocorrer apenas a partir da sua rede, suspeite de um proxy do seu lado
504 Gateway Timeout	504 (não está na documentação do HiAPI)	Gateway ou proxy no caminho que parou de esperar (a documentação do HiAPI não lista 504)	Não dá para saber pela resposta	Igual ao 502; o HiAPI relata seus próprios timeouts como TASK_TIMEOUT
TASK_TIMEOUT	200 + "status": "fail"	HiAPI — a tarefa foi executada, mas excedeu o limite de tempo	Não (o valor reservado foi reembolsado)	Tente novamente a tarefa como uma nova requisição
TASK_FAILED	200 + "status": "fail"	HiAPI — a tarefa foi aceita, executada e então falhou	Não (o valor reservado foi reembolsado)	Tente novamente uma vez e depois leia error.message
429 RATE_LIMITED	429	HiAPI — você enviou rápido demais	Nenhuma tarefa	Aplique backoff; não reenvie imediatamente
400 / 401 / 402	4xx	HiAPI — lado do cliente (erro de corpo/chave/saldo)	Não	Corrija a requisição, a chave ou o saldo; tentar novamente não adianta

Resumo em uma frase: 502/503/504 são erros de transmissão HTTP e não carregam nenhum resultado de tarefa; já TASK_FAILED / TASK_TIMEOUT chegam como HTTP 200 com "status": "fail" e um objeto error. O primeiro caso significa "você não sabe se a requisição foi entregue"; o segundo significa "a requisição foi entregue, a tarefa foi executada e falhou".

Exemplo mínimo de verificação

Use um envio limpo para provar que sua chave e conectividade estão funcionando e isolar o 502/503 como um problema temporário. Use um id de modelo que você sabe estar disponível (por exemplo, gpt-image-2/text-to-image) e inclua o Idempotency-Key para que a nova tentativa seja segura:

# 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"

Se o próprio envio retornar 200 e um taskId, isso significa que sua autenticação e o caminho de rede estão normais, e que o 502/503 anterior foi uma condição temporária do servidor/transmissão — tente novamente a chamada que falhou (reutilizar o mesmo Idempotency-Key retorna a tarefa original, não uma tarefa duplicada). Se o envio retornar 401 ou 400, trata-se de um problema do lado do cliente, não de 502/503.

Leituras relacionadas

• Timeout de tarefa e erro 504 do HiAPI: como corrigir —— por que um 504 bruto não vem do HiAPI e o que significa TASK_TIMEOUT.
• Erro TASK_FAILED do HiAPI: causas e como corrigir —— como tratar tarefas que retornam 200 + "status": "fail".
• Quando um job em hiapi /v1/tasks trava ou expira: diagnóstico e nova tentativa —— aprofundamento sobre intervalos de polling e estratégias de nova tentativa.
• Como corrigir o erro de limite de taxa (429) do HiAPI —— quando o problema real é a taxa de envio e não a disponibilidade.
• Por que requisições com falha do HiAPI ainda são cobradas? —— como funcionam a reserva e o reembolso em tarefas com falha.

Perguntas frequentes

Um 502 ou 503 é culpa minha? Não. Ambos são respostas 5xx, do lado do servidor ou da transmissão. Sua chave de API e o corpo da requisição não são os gatilhos — 4xx (400/401/402) é a categoria causada por você e que você pode corrigir. A resposta correta a um 502/503 é uma nova tentativa idempotente, não alterar o código.

Qual é a diferença entre 502 e 503 no HiAPI? O 503 é o código "plataforma temporariamente indisponível" documentado pelo HiAPI (error_code: TEMPORARILY_UNAVAILABLE), originado na própria plataforma. O 502 não está entre os códigos de status documentados do HiAPI; no HTTP padrão, ele é emitido por um gateway ou proxy no caminho quando o upstream retorna uma resposta inválida. Ambos são temporários e exigem nova tentativa com backoff, mas o 502 também pode apontar para um proxy na sua própria rede.

Qual é a diferença entre 503 e 504? 503 significa que o serviço está temporariamente indisponível ou sobrecarregado no momento. 504 Gateway Timeout significa que algo em algum ponto esperou demais por uma resposta. A documentação do HiAPI não lista 504; se você o vir, significa que um gateway ou proxy em algum ponto do caminho desistiu de esperar. O estado "demorou demais" do próprio HiAPI é o resultado de tarefa TASK_TIMEOUT (HTTP 200 + "status": "fail"). Consulte o guia sobre 504 acima.

Como distinguir 502/503 de um resultado TASK_FAILED? Observe o código de status HTTP. 502/503 são erros HTTP sem payload de tarefa. TASK_FAILED retorna como HTTP 200 com "status": "fail" e um objeto error — a tarefa foi aceita e executada. Use backoff para 502/503; para TASK_FAILED, tente novamente uma vez e depois leia error.message.

Se eu tentar novamente após um 502/503, serei cobrado duas vezes ou criarei uma tarefa duplicada? Não, se você enviar o cabeçalho Idempotency-Key no POST /v1/tasks. Reutilizar a mesma chave + corpo de requisição retorna o taskId original (Idempotent-Replay: true), sem criar uma tarefa duplicada. Além disso, tarefas com falha nunca são cobradas — quando a tarefa atinge um estado terminal de falha, o valor reservado no momento da criação é reembolsado integralmente.

Por quanto tempo devo aplicar backoff e quando devo escalar? Use backoff exponencial com jitter (por exemplo, 1 s, 2 s, 4 s, 8 s, com teto e aleatoriedade). Se o 502/503 continuar retornando após várias tentativas ao longo de alguns minutos, pare as novas tentativas agressivas e entre em contato com o suporte incluindo o request_id do corpo do erro — um 5xx persistente normalmente indica um incidente temporário da plataforma, e não algo que um loop de novas tentativas mais rápido resolva.

Devo modificar o payload da requisição ao ver 502/503? Não. 502/503 não são erros de validação, então alterar parâmetros não ajuda e pode até mascarar a verdadeira causa temporária. Mantenha a requisição inalterada, adicione o Idempotency-Key se ainda não o fez e tente novamente com backoff.