# Handling Long-Running Requests

Apideck exposes two host names for Unified API traffic: `unify.apideck.com` (default and recommended) and `longrun.apideck.com` (opt-in for exceptional workloads). This guide explains when each host applies, how `x-apideck-timeout` controls per-request waiting on the Proxy API, and how to diagnose the different 504 responses you may see.

## The default: `unify.apideck.com`

`unify.apideck.com` serves all normal Unified API and Proxy traffic. Every request has a hard ceiling of roughly **29 seconds**. If the downstream connector does not respond in time, Apideck returns a structured 504 error with `type_name: ProxyTimedOutError` and an `x-apideck-request-id` header you can use for support lookups.

This is the path 99% of traffic should take. Keep your calls on `unify.apideck.com` unless you have a specific reason to opt out.

## Per-request timeout control: `x-apideck-timeout`

On the **Proxy API**, you can set `x-apideck-timeout` to change how long Apideck waits for the downstream vendor before returning a timeout error.

| Property | Value |
|---|---|
| Header name | `x-apideck-timeout` |
| Value unit | Milliseconds (integer) |
| Default when absent or invalid | `28000` |
| Scope | Proxy API only |
| Visibility | Stripped before the request reaches the downstream vendor |

There is no upper bound enforced by the API itself, but the effective ceiling is governed by the host — see the [Ceilings at a glance](#ceilings-at-a-glance) section below.

Example:

```bash
curl https://unify.apideck.com/proxy/accounts \
  -H "Authorization: Bearer <API_KEY>" \
  -H "x-apideck-app-id: <APP_ID>" \
  -H "x-apideck-consumer-id: <CONSUMER_ID>" \
  -H "x-apideck-service-id: <SERVICE_ID>" \
  -H "x-apideck-timeout: 25000"
```

## When to use `longrun.apideck.com`

`longrun.apideck.com` raises the per-request ceiling to roughly **120 seconds**. Use it when **all** of the following apply:

1. **The request is already optimized.** You are using filters, pagination, projection (`fields`), and a narrow `limit`.
2. **The downstream connector is known-slow**, and your optimized call still needs more than ~25 seconds to return.
3. **You need headroom as a workaround**, not as a first-line fix for slow calls.
4. **Anything else exceptional** — bulk one-off reconciliations, pre-seed sync runs, backfills that you cannot paginate further.

### Using `longrun.apideck.com`

Swap the host. Keep the same paths, the same auth headers, and the same request body. If you want Apideck to wait beyond the 28-second default, pass `x-apideck-timeout` with a larger value.

```bash
curl https://longrun.apideck.com/proxy/transactions \
  -H "Authorization: Bearer <API_KEY>" \
  -H "x-apideck-app-id: <APP_ID>" \
  -H "x-apideck-consumer-id: <CONSUMER_ID>" \
  -H "x-apideck-service-id: <SERVICE_ID>" \
  -H "x-apideck-timeout: 90000"
```

## Ceilings at a glance

| Host | Ceiling | Error shape on timeout |
|---|---|---|
| `unify.apideck.com` | ~29 s | `{"message":"Endpoint request timed out"}` (no request-id) |
| `longrun.apideck.com` | ~120 s | HTML 504 page from the network edge |
| Either host, when Apideck detects the slow downstream first | Default 28 s, or your `x-apideck-timeout` | Apideck JSON with `type_name: ProxyTimedOutError` and `x-apideck-request-id` |

## When NOT to use `longrun.apideck.com`

- **As a shortcut to avoid adding filters or pagination.** Optimize the request first.
- **For latency-critical interactive flows.** Longrun trades latency ceiling for responsiveness — it is not meant for requests that need to return fast.
- **For general production traffic.** Stay on `unify.apideck.com`. Longrun is opt-in per call, not an account-level switch.

## Diagnosing a 504

When a request times out, the response body tells you which layer cut it off:

- **Apideck JSON with `type_name: ProxyTimedOutError` and an `x-apideck-request-id` header** — Apideck's Proxy returned the timeout first. Check the request ID with support if you need more detail.
- **JSON body `{"message":"Endpoint request timed out"}` with no request-id** — the host's gateway cut off the request at its ceiling. On `unify.apideck.com` that means you hit the ~29 s limit; consider optimizing the call or moving to `longrun.apideck.com`.
- **HTML 504 page** — the network edge in front of `longrun.apideck.com` cut the request at the ~120 s ceiling. The call ran for roughly two minutes without the downstream responding; investigate the downstream connector directly.

>
> `unify.apideck.com` is the default and recommended host. `longrun.apideck.com` is opt-in on a per-call basis — there is no account-level switch, and you should route only the specific requests that need the higher ceiling.

## Using the SDKs

Apideck SDKs expose both the host override and per-request custom headers, so you can reach `longrun.apideck.com` and set `x-apideck-timeout` without constructing raw HTTP requests.

### TypeScript (`@apideck/unify`)

Override the base URL with the `serverURL` constructor option, then pass `x-apideck-timeout` as a per-call header:

```typescript
import { Apideck } from '@apideck/unify'

const apideck = new Apideck({
  serverURL: 'https://longrun.apideck.com',
  apiKey: process.env.APIDECK_API_KEY!,
  appId: process.env.APIDECK_APP_ID!,
  consumerId: 'your-consumer-id'
})

const result = await apideck.proxy.get(
  {
    serviceId: 'netsuite',
    unifiedApi: 'accounting',
    downstreamUrl: 'https://webservices.netsuite.com/services/NetSuitePort_2024_2'
  },
  {
    headers: {
      'x-apideck-timeout': '90000'
    }
  }
)
```

The second argument to any `apideck.proxy.*` method (`get`, `post`, `put`, `patch`, `delete`, `options`) is a `RequestOptions` object whose `headers` field is merged into the outgoing request. Source: [apideck-libraries/sdk-typescript](https://github.com/apideck-libraries/sdk-typescript).

### Other SDKs

The same two controls — a server URL override and per-request custom headers — are available in every Apideck SDK. Constructor option and per-request header syntax varies per language:

| SDK | Repository |
|---|---|
| TypeScript | [apideck-libraries/sdk-typescript](https://github.com/apideck-libraries/sdk-typescript) |
| Python | [apideck-libraries/sdk-python](https://github.com/apideck-libraries/sdk-python) |
| PHP | [apideck-libraries/sdk-php](https://github.com/apideck-libraries/sdk-php) |
| Java | [apideck-libraries/sdk-java](https://github.com/apideck-libraries/sdk-java) |
| .NET / C# | [apideck-libraries/sdk-csharp](https://github.com/apideck-libraries/sdk-csharp) |
| Go | [apideck-libraries/sdk-go](https://github.com/apideck-libraries/sdk-go) |

See the [SDKs overview](/sdks) for install instructions and per-language examples.

## Related references

- [Proxy API reference](/apis/proxy/reference)
- [Unified Rate Limits](/guides/unified-rate-limits)
- [Errors index](/errors) — see `ProxyTimedOutError`