> For the complete documentation index, see [llms.txt](https://docs.apismart.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.apismart.ai/troubleshooting/timeout-and-connection-issues.md).

# Timeout and Connection Issues

Troubleshoot ApiSmart request timeouts, connection issues, temporary service errors, and long-running image and video generation requests.

Some ApiSmart requests can take longer than ordinary API calls, especially image and video generation.

If a request times out or returns a temporary `5xx` error, first determine whether the issue is caused by your client timeout, a long-running generation, or a temporary upstream service problem.

### ⏱️ Image Request Timeouts

Image generation is synchronous by default.

When you call:

```
POST /v1/images/generations
```

the connection remains open until generation completes and the result is returned.

A single image typically takes around **20–40 seconds**. High-resolution images, multiple reference images, or sequential generation may take longer.

Set your client timeout to at least:

```
90 seconds
```

Using a slightly longer value such as **120 seconds** can provide additional margin.

> **Important:** A client timeout does not necessarily mean generation failed. The image may still finish and incur a charge even if your client disconnects before receiving the result.

If this happens, check [**Generated Media History**](/api-usage/generated-media-history.md) or [**Usage Logs and Costs**](/api-usage/usage-logs-and-costs.md) before immediately sending the same request again.

### 🎬 Video Requests Should Not Wait for Completion

Video generation uses an asynchronous task workflow.

Create the video task first, then query its status separately.

```
POST /v1/video/tasks
        ↓
Receive task ID
        ↓
GET /v1/video/tasks/{id}
```

While generation is in progress, the task can return:

| Status      | Meaning                |
| ----------- | ---------------------- |
| `queued`    | Waiting in queue       |
| `running`   | Generation in progress |
| `succeeded` | Generation completed   |
| `failed`    | Generation failed      |
| `cancelled` | Task was cancelled     |
| `expired`   | Task expired           |

Do not keep the original video creation request open while waiting for the final video.

Continue querying the task while its status is `queued` or `running`.

For the complete workflow, see [**Video Generation API**](/api-guides/video-generation-api.md).

### 🔌 502 — Gateway or Upstream Error

A `502` response can indicate a temporary problem between ApiSmart and an upstream model service or network layer.

Possible codes include:

```
proxy_error
BadGateway
```

These errors may be temporary.

Wait briefly and retry using exponential backoff rather than sending repeated requests immediately.

### ⚠️ 503 — Service Temporarily Unavailable

A `503` can indicate that a dependent service is temporarily unavailable.

Possible codes include:

| Code                              | Meaning                                         |
| --------------------------------- | ----------------------------------------------- |
| `provider_not_available`          | Model provider temporarily unavailable          |
| `quota_service_unavailable`       | Quota service temporarily unavailable           |
| `proxy_unavailable`               | Proxy dependency temporarily unavailable        |
| `asset_owner_service_unavailable` | Asset ownership service temporarily unavailable |

If the response provides `Retry-After`, wait for the indicated period before retrying.

Also verify the model ID if the `503` appeared immediately after changing models. ApiSmart model IDs must match exactly.

### ⌛ 504 — Gateway Timeout

A `504 GatewayTimeout` indicates that an upstream service did not respond within the expected time.

This can be a temporary service or network-layer issue.

Recommended handling is to wait and retry using controlled exponential backoff.

For example:

```
1 second → 2 seconds → 4 seconds → 8 seconds
```

Stop after a reasonable number of attempts instead of retrying indefinitely.

### 🔁 Retry Temporary Errors Carefully

For temporary connection or service failures such as `502`, `503`, and `504`, use controlled retries.

A good retry strategy should:

* Wait between attempts
* Increase the delay after repeated failures
* Follow `Retry-After` when provided
* Set a maximum number of retries
* Avoid retrying the same request continuously

Do not automatically apply this retry strategy to invalid parameters, authentication failures, or insufficient balance.

For complete retry guidance, see [**HTTP Status Codes and API Errors**](/troubleshooting/http-status-codes-and-api-errors.md).

### 🔎 Request Timed Out but You Are Not Sure What Happened

Before submitting the same request again, check whether it may already have completed.

For image generation, review [**Generated Media History**](/api-usage/generated-media-history.md) and [**Usage Logs and Costs**](/api-usage/usage-logs-and-costs.md).

For video generation, query:

```
GET /v1/video/tasks/{id}
```

using the task ID returned when the task was created.

This can help avoid unnecessary duplicate generations and additional costs.

### ✅ Quick Troubleshooting Checklist

When a request times out or loses connection, check the endpoint first: use at least a 90-second timeout for synchronous image generation, poll video tasks instead of waiting for completion, and retry `502`, `503`, or `504` only with controlled backoff. If a request may already have completed, check its task status, media history, or Usage Logs before submitting it again.

For other failures, see [**HTTP Status Codes and API Errors**](/troubleshooting/http-status-codes-and-api-errors.md).

### ➡️ Next Steps

[**HTTP Status Codes and API Errors**](/troubleshooting/http-status-codes-and-api-errors.md) — Review all API error codes\
[**Image Generation API**](/api-guides/image-generation-api.md) — Understand synchronous image requests\
[**Video Generation API**](/api-guides/video-generation-api.md) — Understand asynchronous video tasks\
[**Usage Logs and Costs**](/api-usage/usage-logs-and-costs.md) — Investigate request activity and costs\
[**Generated Media History**](/api-usage/generated-media-history.md) — Check recent generated media