# Phone won't start

Source: https://phonebox.dev/docs/troubleshooting/phone-wont-start

> Why a create or start is refused, what a failed phone means, and how long a phone has to become ready.



Start with the error's `code`. A refused create or start reserves nothing and costs nothing, and a phone that fails before it is ever ready costs nothing either.

## capacity\_unavailable [#capacity_unavailable]

`503 capacity_unavailable` means no phones are free right now. It comes in two forms:

* **The request is refused.** No phone was created or started, and nothing was reserved. Send the same request again after `Retry-After`, which is 30 seconds unless it says otherwise. Repeat a create with the same `Idempotency-Key`. When a few tries in a row are refused, stop and tell your user, and try again later.
* **A phone couldn't get a device.** The error names the phone in `details.phone`, or you find the phone with its `failure.code` set to `capacity_unavailable`. A new phone is then `failed`, and the error isn't retryable, so create another one later, with a new idempotency key if you use one. An existing phone parks again with its data, so start it again later.

## insufficient\_credits [#insufficient_credits]

`402 insufficient_credits` means your balance, minus what running phones have reserved, can't cover the new session's reservation. The reservation is the whole `max_duration` at $0.001 a second, so the default hour needs $3.60.

* `details.max_affordable_seconds` is the longest `max_duration` you can afford right now. When it is 60 or more, `next` suggests it.
* Start with a shorter `max_duration`, add credits in [Billing](/app/billing), or park your own running phones that you no longer need to release what they reserved.

## running\_limit\_reached [#running_limit_reached]

`409 running_limit_reached` means the project already runs as many phones as it may, 2 by default. The limit counts all of your projects together. `details.limit` is the limit.

* Park only a phone you created for this task and no longer need. A phone counts as running while it is `creating`, `starting` or `ready`, so list each of those statuses to find yours, such as `GET /v1/phones?status=ready`.
* Never park a phone that another agent or a person may be using: its work stops mid-task, and starting that phone again opens a new billed session. When you have no phone of your own to park, stop and tell your user.
* Check the limit in Settings, where it may have been lowered, and email [team@phonebox.dev](mailto:team@phonebox.dev) if you need a higher limit than Settings offers.

## service\_paused [#service_paused]

`503 service_paused` means Phonebox is paused for maintenance. Creates and starts are refused, and running phones are parked, with the end reason `service_paused`. Your phones and everything on them are kept. Try again later.

## Other refusals [#other-refusals]

| Error                                   | What to do                                                                                                                                                                |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `402 spend_limit_reached`               | The session would take this month's spending past the monthly limit. Raise it in Settings, or start with a shorter `max_duration`.                                        |
| `402 project_frozen`                    | Contact support. A refund that leaves too little credit, or a review of the project's use, freezes a project.                                                             |
| `409 phone_limit_reached`               | Delete only a phone you created and no longer need. In a project that several agents share, tell your user instead, or ask for a higher limit. Failed phones don't count. |
| `409 phone_parking`                     | The phone is still parking. Wait with `GET /v1/phones/{id}?wait=parked`, then start it.                                                                                   |
| `409 phone_failed`, `409 phone_deleted` | The phone can't be started again. Create a new one, with a new idempotency key if you use one.                                                                            |
| `429 rate_limited`                      | The project made 60 creates, starts, parks and deletes this minute. Wait for `Retry-After`.                                                                               |
| `403 insufficient_scope`                | Creating needs `phones:create`, which keys limited to certain phones never have.                                                                                          |

## When a phone fails [#when-a-phone-fails]

A phone whose setup fails, or whose device is lost, becomes `failed`, and its `failure` field says why, with a `code`, a `message` and the time. Common codes are `provider_timeout`, when it didn't become ready in time, `capacity_unavailable`, and `validation_failed`, when no phones are available in the `country` you asked for.

* A session that fails before the phone was ever ready costs nothing, and the reservation is released.
* A failed phone can't be started again. Create a new one.
* A failed phone holds no device and doesn't count toward your phone limit, so you don't need to delete it.

## How long a phone has to become ready [#how-long-a-phone-has-to-become-ready]

A phone is `ready` only after its screen has answered a read and a screenshot has succeeded. A new phone has 10 minutes from its create to get there, and often takes about a minute. When the 10 minutes run out, it fails with `provider_timeout`, at no charge.

A start of a parked phone has 5 minutes. When they run out, the phone parks again with its apps and data, and its `failure` records why. Start it again later.

Waiting that long takes more than one request. Create and start each wait about 50 seconds, and then answer `202 Accepted` with the phone still `creating` or `starting`. Keep polling `GET /v1/phones/{id}?wait=ready&timeout=50` while the phone is `creating` or `starting`, and stop at any other status: `ready` means the phone is yours to use, and the other statuses are explained above. The CLI and the SDK do this for you, for up to 10 minutes for a create and 5 for a start.

## A phone that is unavailable [#a-phone-that-is-unavailable]

`unavailable` means the phone went into maintenance, or its state couldn't be confirmed. Its session was closed, so it isn't billed, and its data is kept. Start it again later. A start that meets maintenance leaves the phone `unavailable` at no charge, and a start request that is still waiting then answers `503 phone_unavailable` with the phone in `details.phone`.
