> Fetch the index of every Tonbo docs page as Markdown at https://tonbo.dev/llms.txt

# Request guarantees

Last updated 2 November 2026

> Machines are not open yet. These pages describe Machines as they will open; until then, a create answers [`region_not_offered`](https://tonbo.dev/docs/machines/troubleshooting/manage.md#region_not_offered) (422), “Machines are not offered in any region yet.”

Rely on each request reaching your program at most once, and on an open request keeping your Machine awake.

- Tonbo never sends your Machine a request it has already received.
- A request in flight keeps the Machine from sleeping for being idle.
- With no host free, a wake waits up to 25 s, then answers `503` with `Retry-After`.
- A request ended with `502` may have run: send an `Idempotency-Key` with any request that must not run twice.
- A wake needs credit for the Machine’s first ten minutes.

Ports, keys and what reaches your program are on [Serve requests](https://tonbo.dev/docs/machines/requests.md).

## Each request at most once

Tonbo never sends your Machine a request twice. When it must put a busy Machine to sleep, it lets requests in progress finish for a few seconds, then ends the rest with `502`; such a request may or may not have run.

- The text below also names inbox events, which Tonbo does not serve.

> **Word for word**
>
> - **Requests and sleep.** Tonbo never repeats a request your Machine has received, and a Machine with a request in flight is never put to sleep for being idle. When Tonbo has to put such a Machine to sleep, to remove a host or to patch one, it first stops sending it new requests and waits a few seconds for the ones in progress. A request still running when that wait ends is ended with 502, and it may or may not have run. A request to a sleeping Machine wakes it. If no host has room, the request waits up to 25 s and is then answered 503 with Retry-After; inbox events are kept, and they wake the Machine once a host has room. Send an Idempotency-Key with any request that must not run twice.

The `503` a wake can answer is under [When no host has room](#capacity), and when to retry it is [a rule](https://tonbo.dev/docs/machines/rules/requests.md#retry) of its own.

## When no host has room

A wake with no host free waits, then answers `503`; a host Tonbo removes first gets time for its Machines to sleep on their own. The name at the end of the text is internal, and no command or API shows it.

> **Word for word**
>
> If no host has room for a wake, the request waits up to 25 s and is then answered 503 with Retry-After while Tonbo adds a host. When Tonbo removes a host it no longer needs, it first waits up to 6 hours for that host's Machines to go to sleep on their own. It then puts the rest to sleep, connected ones included, and their next request wakes them on another host. That sleep shows as `host_removed`.

The answer and what to do about it are on [Troubleshooting](https://tonbo.dev/docs/machines/troubleshooting/call.md#capacity).

## When credit runs short

A wake needs credit for the Machine’s first ten minutes at its shape’s full price; when your balance cannot pay for the next ten, the Machine stops and wakes again once credit is added.

- The name in brackets, below, is the stop reason the Machine’s activations show.

> **Word for word**
>
> A wake needs enough credit for the Machine's first ten minutes at its shape's full price, and each later ten minutes is paid for before it starts. When your balance cannot pay for the next ten minutes, the Machine is stopped (`funding_stop`), and it can wake again once credit is added. Its database use is billed as it is metered.

What ten minutes costs for each shape is on [Pricing](https://tonbo.dev/docs/machines/pricing.md#credit).