> ## Documentation Index
> Fetch the complete documentation index at: https://repost.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure Forwarder Routing, Timeouts, and Retry Rules

> Adjust forwarder destination, path mode, timeout, retries, rate limits, and circuit breaker from the Repost dashboard settings page.

A forwarder's settings page answers four questions about each destination: where should requests go, how long should Repost wait for a response, which failed attempts should be retried, and when should delivery pause or stop entirely. All of these settings are available after creation and can be changed without recreating the forwarder.

## Settings overview

The settings page is divided into named sections. General and Routing sections use an explicit **Save** button. Timeout, retry, rate-limit, and circuit-breaker controls save automatically when you release a slider or toggle a switch.

<CardGroup cols={2}>
  <Card title="General" icon="settings">
    Rename the forwarder. The type is displayed here because it shapes behavior, but you cannot change `EXTERNAL` to `INTERNAL` or the reverse after creation.
  </Card>

  <Card title="Routing" icon="route">
    Choose `TRANSPARENT` or `LOCKED` path mode, then set `http` or `https` and the `host[:port][/path]` destination.
  </Card>

  <Card title="Timeout" icon="timer">
    Set the maximum time Repost waits for a destination response before marking the attempt as timed out. The slider saves when you release it.
  </Card>

  <Card title="Retry configuration" icon="repeat">
    Enable or disable asynchronous retries and tune the retry schedule. Hidden for proxy bucket forwarders.
  </Card>

  <Card title="Rate limiting" icon="gauge">
    Cap per-forwarder delivery throughput. The switch saves when toggled; the slider saves when released. Hidden for proxy bucket forwarders.
  </Card>

  <Card title="Circuit breaker" icon="shield-check">
    Block delivery attempts after repeated downstream failures so the destination has time to recover. Available for external forwarders only.
  </Card>
</CardGroup>

## Destination and routing

These settings define the request Repost constructs before sending it to the destination.

<CardGroup cols={2}>
  <Card title="External forwarder" icon="globe">
    Delivers to a public HTTP endpoint. The destination must use `http` or `https` and cannot point to localhost, private networks, single-label hostnames, or internal-only hostnames.
  </Card>

  <Card title="Internal forwarder" icon="laptop">
    Delivers to a developer machine through `repost forward`. Local hostnames such as `localhost:3000` are allowed because the CLI performs the final local hop.
  </Card>
</CardGroup>

<Warning>
  Forwarder type is immutable after creation. If you need to move a destination from external delivery to CLI delivery, or vice versa, create a new forwarder with the correct type.
</Warning>

<Tabs>
  <Tab title="Transparent mode">
    Repost treats the configured destination as a base URL and appends the original incoming request path. A request to `/webhooks/stripe` with destination `https://api.example.com` is forwarded to `https://api.example.com/webhooks/stripe`.
  </Tab>

  <Tab title="Locked mode">
    Repost always delivers to the exact configured destination regardless of the incoming path. A request to `/webhooks/stripe` with destination `https://api.example.com/hook` is forwarded to `https://api.example.com/hook`.
  </Tab>

  <Tab title="Destination format">
    The dashboard separates the protocol from the destination. Choose `http` or `https`, then enter `host[:port][/path]` without the protocol prefix. Repost saves these as a single destination URL.
  </Tab>
</Tabs>

<Note>
  When saving an external destination, Repost validates the target. If DNS answers are available, Repost also checks whether the hostname resolves to a blocked address (localhost, private IPs, single-label hostnames, or internal-only hostnames).
</Note>

## Timeout

The timeout slider sets the maximum time Repost waits for a destination response on any single delivery attempt.

<ParamField body="Timeout" type="integer">
  Range: `5000`–`60000` ms in `1000` ms steps. Default: `20000` ms. The slider saves automatically when you release it.
</ParamField>

## Retry configuration (queue buckets only)

Retry settings control what happens after a failed delivery attempt. These controls are hidden for proxy bucket forwarders because the provider connection waits on a single synchronous response.

<ParamField body="Retries enabled" type="boolean">
  Toggle to enable or disable retries. The switch saves immediately when toggled. Disabling retries sets the count to `0`; re-enabling restores the last positive value shown in the dashboard.
</ParamField>

<ParamField body="Max retries" type="integer">
  Range: `0`–`3`. Default at creation: `3`. Setting to `0` is equivalent to disabling retries with the toggle.
</ParamField>

<ParamField body="Retry delay" type="integer">
  Range: `5000`–`60000` ms in `1000` ms steps. Default: `15000` ms. Sets the initial retry window.
</ParamField>

<ParamField body="Backoff multiplier" type="number">
  Range: `0.5x`–`3.0x` in `0.5x` steps. Default: `2.0x`. Each failed attempt multiplies the retry window by this value.
</ParamField>

<ParamField body="Max retry delay" type="integer">
  Range: `60000`–`1800000` ms in one-minute steps. Default: `900000` ms. Caps the retry window regardless of the backoff multiplier.
</ParamField>

<Note>
  Retry waits use full jitter. Repost picks a delay between `0` and the current retry window, floors it at `1000` ms, then grows the window by the backoff multiplier until capped by the max retry delay.
</Note>

Repost retries connection failures and responses with status `408`, `429`, or `5xx`. All other `4xx` responses are treated as final and are not retried.

## Rate limiting (queue buckets only)

Rate limiting caps how many requests per second this forwarder delivers to its destination. The control is hidden for proxy bucket forwarders.

<ParamField body="Rate limit enabled" type="boolean">
  Off by default. The switch saves immediately when toggled.
</ParamField>

<ParamField body="Rate limit" type="integer">
  Range: `5`–`500` requests per second in steps of `5`. The dashboard starts the slider at `50` before the first save.
</ParamField>

## Circuit breaker (external forwarders only)

The circuit breaker prevents Repost from sending requests to a destination that is repeatedly failing, giving the downstream service time to recover.

<ParamField body="Circuit breaker enabled" type="boolean">
  The switch saves immediately when toggled. Disable it only when every event must attempt delivery regardless of downstream health.
</ParamField>

## Forwarder lifecycle

Lifecycle state controls whether a forwarder participates in delivery without requiring you to change its destination or delivery settings.

<CardGroup cols={2}>
  <Card title="Active switch" icon="toggle-right">
    When disabled, the forwarder stays configured but stops participating in delivery. Re-enable it at any time to resume.
  </Card>

  <Card title="Pause and resume" icon="pause">
    Pause holds delivery for an active forwarder without disabling it. Resume restarts delivery and preserves the saved rate limit. For internal forwarders, the pause control appears only while a CLI listener is connected.
  </Card>

  <Card title="Internal listener state" icon="terminal">
    Internal forwarders show **No listeners** when active but no CLI session is connected. If a listener drops, Repost marks the forwarder as disconnected and holds delivery until you reconnect using `repost forward`.
  </Card>

  <Card title="Delete" icon="trash">
    Deletion requires you to type the exact forwarder name to confirm. It permanently removes the forwarder and its full request and response history. Deletion is blocked while any replay job is pending, estimating, processing, or paused.
  </Card>
</CardGroup>

## Why a settings save can be rejected

<AccordionGroup>
  <Accordion title="Forwarder not found">
    The forwarder must belong to the current workspace through its bucket. Verify you are working in the correct workspace.
  </Accordion>

  <Accordion title="Forwarder type cannot be changed">
    Type is set at creation and is immutable. You can change the name, destination, routing, timeout, retry settings, and rate limit — but not the type.
  </Accordion>

  <Accordion title="External destination blocked">
    External forwarders cannot point to localhost, private or reserved IP ranges, single-label hostnames, internal-only hostnames, or hostnames that resolve to blocked addresses.
  </Accordion>

  <Accordion title="Proxy bucket rejected retry or rate controls">
    Proxy forwarders do not support retry configuration or a non-null rate limit. Move to a queued bucket to use these controls.
  </Accordion>

  <Accordion title="Delete blocked by active replay">
    Cancel the replay or wait for it to finish before deleting the forwarder.
  </Accordion>
</AccordionGroup>