Concepts
Activation lifecycle
States, timeouts, and status transitions of a number activation.
Every activation moves through a small state machine.
waiting_code ──SMS arrives──> completed (payment settles)
waiting_code ──cancel──> cancelled ($0 settled)
waiting_code ──~18 min──> expired ($0 settled)
completed ──retry──> waiting_code (another SMS, free)States
| State | Meaning | Charged? |
|---|---|---|
waiting_code | Number issued, waiting for SMS | Not yet |
completed | SMS code delivered, payment settled | Yes |
cancelled | Cancelled by you before delivery | $0 |
expired | Number timed out | $0 |
Timing
- Numbers stay active for ~18 minutes from issuance (see
expiresAt) - After the first code arrives you can request another SMS for the same
number via
POST /v1/numbers/{id}/retry— additional codes within the number's lifetime are delivered at no extra charge - A background sweeper retires stale activations automatically; they appear as
expired
Access control
Ordering returns an accessToken. It is required for status polls, cancel, and
retry — pass it as Authorization: Bearer <token> (preferred) or
?token=<token>. Tokens are per-activation and unguessable; there are no
accounts and no cross-activation permissions.
Errors worth handling
| HTTP | Cause | Your payment |
|---|---|---|
409 NO_NUMBERS | No numbers for that service/country/operator right now | Never settled — retry later or change country/operator |
503 NO_BALANCE | Activation capacity temporarily exhausted | Never settled — retry later |
| 502 | Settlement or temporary service failure | Poll again; settlement retries automatically |
| 409 in-progress | A settle/cancel is currently running for this activation | Wait a few seconds and poll again |