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

# Troubleshooting: calling a Machine

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.”

Look up the answer a request to a Machine’s name got when it was refused: why, and what to do.

The refusal names its code in the answer’s `code`.

| Answer | Why | What to do |
| --- | --- | --- |
| `401 unauthenticated` | A private port needs Authorization: Bearer with a key of your account. | Send a personal key (see [Private ports](https://tonbo.dev/docs/machines/requests.md#private-ports)). |
| `401 exchange_required` | An Agent’s key is exchanged for an access token before it calls a private port. | Exchange it and send the token (see [the token exchange](https://tonbo.dev/docs/platform/api-keys.md#exchange)). |
| `503 authorization_uncertain` | Tonbo could not check the key or the Machine in time; nothing ran. | Send it again; Retry-After says when, 15 seconds at first. |
| `404 machine_host_unknown` | No Machine has this HTTPS name in this region. | Check the name, the account and the region in the URL. |
| `404 machine_not_found` | The name was deleted, or never existed. | `tonbo machine list` shows your Machines. |
| `404 port_not_served` | The Machine declares no such port; the detail lists its ports. | Call a declared port, or add one with tonbo machine update --port. |
| `405 method_not_allowed` | CONNECT is not served. | Send HTTP/1.1, Server-Sent Events or WebSocket. |
| `409 machine_not_ready` | It is still being created, or its creation failed. | `tonbo machine show` says which. |
| `410 machine_deleting` | It is being deleted. | Create a new Machine under the same name: it takes over the same HTTPS names. |
| `503 machine_waking` | It is still starting after 25 seconds, or your program is not listening on the port yet. | Send it again after Retry-After. If it lasts, make your program listen on `0.0.0.0` at the declared port within seconds (see [The first request](https://tonbo.dev/docs/machines/requests.md#first-request)). |
| `503 image_pulling` | Its image is being pulled, after a change of image or on another host. | Send it again; Retry-After says when, 5 seconds at first. |
| `409 image_failed` | Its image cannot be pulled; `tonbo machine show` says why. | Fix the image and name it again (see [While the new image is pulled](https://tonbo.dev/docs/machines/deploy.md#pulling)). |
| `402 payment_required` | Your credit does not cover the wake’s first ten minutes at the shape’s full price. | Add credit (see [Credit](https://tonbo.dev/docs/machines/pricing.md#credit)). |
| `503 money_uncertain` | Tonbo could not confirm the credit for the wake; nothing ran. | Send it again; Retry-After says when, 15 seconds at first. |
| `503 token_unavailable` | Tonbo could not prepare the Machine’s access to its database; nothing ran. | Send it again; Retry-After says when, 15 seconds at first. |
| `503 capacity` | No host could take the Machine right now. | Send it again; Retry-After says when, 30 seconds at first. |
| `503 node_unavailable` | The host chosen for the Machine did not answer. | Send it again; Retry-After says when, 30 seconds at first. |
| `503 region_closed` | Machines are closed in the region. | Send it again later. |
| `429 crash_backoff` | 3 wakes failed within 5 minutes, for example because your program exits as it starts. | Fix the program (try it on your computer first, see [Try it first](https://tonbo.dev/docs/machines/images.md#local)); wakes are taken again after Retry-After. |
| `502 edge_upstream_unavailable` | Tonbo got no answer from the Machine, or from its own services. | A request that reached your program may or may not have run: send again only what is safe to repeat. |
| `503 machine_unavailable` | What a caller on a public port gets for any refusal above, without the reason. | Send it again after Retry-After; members see the reason on a private port and in `tonbo machine show`. |