Phone won't 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
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 sameIdempotency-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 itsfailure.codeset tocapacity_unavailable. A new phone is thenfailed, 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
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_secondsis the longestmax_durationyou can afford right now. When it is 60 or more,nextsuggests it.- Start with a shorter
max_duration, add credits in Billing, or park your own running phones that you no longer need to release what they reserved.
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,startingorready, so list each of those statuses to find yours, such asGET /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 if you need a higher limit than Settings offers.
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
| 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
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
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
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.