HiAPI Task Timeout and 504 Errors: How to Fix Them

A HiAPI task can fail with a "status": "fail" and "error": {"code": "TASK_TIMEOUT", "message": "Task timed out"} inside an otherwise normal 200 response from GET /v1/tasks/{id} — that's a real, documented HiAPI failure state meaning the task started but didn't finish before its time budget ran out. If instead your own client is throwing a raw HTTP 504 Gateway Timeout, that response did not come from HiAPI's API at all: 504 doesn't appear anywhere in HiAPI's documented status codes. This guide covers both — how to read and fix a genuine TASK_TIMEOUT, and where a 504 actually comes from.

What the error actually looks like

HiAPI's task flow is asynchronous: POST /v1/tasks returns a taskId immediately, and you poll GET /v1/tasks/{id} for the result. A task only has an error once its status reaches a terminal state. A genuine timeout looks like this:

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

Notice the HTTP status on that response is 200 — the poll request succeeded; it's the task that failed, and the failure detail lives in data.error. This is different from a synchronous creation-time failure (like 402 for insufficient balance, or 400 for an invalid request body), which HiAPI returns immediately on the original POST /v1/tasks call, before any task exists. TASK_TIMEOUT can only happen to a task that was already created successfully.

A 504, on the other hand, isn't a response body at all in most cases — it's an HTTP status code that proxies, load balancers, and some HTTP client libraries return when they stop waiting for any response. HiAPI's documented HTTP status codes are 200, 400, 402, 404, 409, 415, 422, and 503 — 504 is not among them. If you're seeing a 401 instead, that's a different problem entirely (an invalid or disabled API key, not a timeout) — see the Invalid API Key Errors guide.

Common causes, most likely first

1. A genuine task-level timeout. The model picked up your task but didn't finish inside its internal time budget. This is the real TASK_TIMEOUT case above, and it's more common on heavier jobs — longer video durations, higher resolutions, or a model that's temporarily under load.
2. A 504 generated outside HiAPI. Most "504" reports are actually a client-side read-timeout (your HTTP library gave up waiting) or a corporate proxy/VPN/load balancer sitting between you and api.hiapi.ai enforcing its own timeout. Since HiAPI never issues a 504, this is a client- or network-side setting, not a HiAPI failure.
3. A task that's still in progress, mistaken for timed out. queued, handling, and archiving are all non-terminal states — no error field exists yet. Polling once and seeing a non-success status isn't a timeout; it's normal.

Fix it in order

1. Pull the task by ID and read status and error.code directly. Don't infer the cause from a generic exception message in your client code — call GET /v1/tasks/{id} and look at the actual response body.
2. If status is "fail" and error.code is "TASK_TIMEOUT": retry. The documented remedy is exactly that — submit the request again as a new POST /v1/tasks call (a fresh taskId). No account or key change is needed.
3. If the job is a heavy one, consider the inputs. Longer video durations, higher resolutions, or very large/complex prompts push a model closer to its time budget. If the same configuration times out repeatedly, try a lighter resolution/duration or a different model.
4. If what you're actually seeing is a bare 504 (not a JSON body with error.code), the problem is outside HiAPI. Check the read/request timeout configured in your own HTTP client or SDK — many default to something short (10–30 seconds), which is too short for an async flow where you should be polling separately rather than blocking on one long request. Also check whether you're going through a corporate proxy, VPN gateway, or load balancer that could be enforcing its own timeout independent of HiAPI.
5. If status is still queued, handling, or archiving, don't retry at all. Nothing has failed. See the task-hang diagnosis guide for the fuller breakdown of why a task can be slow without actually failing.

Minimal verification example

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

This returns a taskId right away:

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

Then poll it:

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

A healthy task eventually returns "status": "success" with output. A genuinely timed-out task returns the TASK_TIMEOUT shape shown earlier. If you instead get a connection-level 504 with no JSON body at all, that confirms the response never made it back from HiAPI's API — check your own client timeout and network path per the steps above, not your HiAPI account.

Related

• When a hiapi /v1/tasks Job Hangs or Times Out: Diagnosis and Retry
• hiapi 'model not available' / 'model not found' errors: causes and fixes
• How to Fix HiAPI Rate Limit (429) Errors
• Creating an async task
• HiAPI dashboard

FAQ

Is HiAPI's TASK_TIMEOUT the same thing as an HTTP 504 Gateway Timeout? No. TASK_TIMEOUT is a documented HiAPI error code returned inside a normal 200 response once a task's status becomes fail — it means the task itself ran out of time internally. A 504 is a generic HTTP status some proxies, load balancers, and HTTP client libraries return when they stop waiting for a response; HiAPI's API doesn't document or emit 504 at all, so a literal 504 means something between you and HiAPI — or your own client — gave up, not HiAPI's servers.

What should I do when I get TASK_TIMEOUT? Submit the request again as a new task. The documented remedy for TASK_TIMEOUT is simply to retry — there's no separate unlock step, and you don't need to change your prompt or parameters unless the exact same input keeps timing out repeatedly.

Will retrying a timed-out task charge me twice? That isn't specified in HiAPI's documented error-code table one way or the other. If it matters for your use case, check your account's usage history for the specific taskId rather than assuming either way.

My HTTP client raised a timeout exception, not a JSON TASK_TIMEOUT — is that the same thing? No. A client-side timeout (for example a ReadTimeout from your HTTP library, or a 504 from a corporate proxy) means your own connection gave up before getting any response from HiAPI — it isn't evidence the task itself failed. Since /v1/tasks is asynchronous, the usual fix is to raise your client's read-timeout (or stop blocking on the initial POST at all) and poll GET /v1/tasks/{id} separately until you see a terminal status.

My task has been queued or handling for several minutes with no error — is that a timeout? Not yet. queued, handling, and archiving are all non-terminal, in-progress states — no error field exists until status becomes fail. If a task genuinely never resolves, see the task-hang diagnosis guide for the fuller breakdown of queue backlog and other in-progress causes.