Responses and errors

Envelope

Responses are JSON with a success flag.

{ "success": true, "numbers": [] }

On failure success is false and error explains why.

{ "success": false, "error": "number zorunludur" }

Error messages are not a stable interface

error is a human-readable string and is currently in Turkish for many validation errors (for example number zorunludur means “number is required”). Branch on the HTTP status code and on documented values such as "timeout", never on message text.

Status codes

Status	Meaning
200	The request was handled. For wait endpoints, also used for a timeout: check the body.
400	A parameter is missing or malformed (including an invalid X-Service-Timeout, or a regex that does not compile).
401	The X-API-Key header is missing or invalid.
403	Not allowed, for example reading an OAuth result that belongs to another project.
404	The thing you named does not exist for your project (a number, a mailbox, an attachment).
499	You closed the connection before the response was ready. Nothing is sent.
502	The upstream provider (Twilio, Hero SMS, a captcha solver) failed.

Provider failures are not always HTTP errors

• Captchas return the provider’s own response, unmodified. When a solver reports that it could not solve the captcha (for example 2Captcha’s code: "ERROR_..." or NoneCap’s status: "failed"), the HTTP status is still 200. Read the failure from the provider-specific fields, or use the SDK, which raises a typed error.
• Batch rentals (phone_numbers on Twilio, quantity on Hero SMS) return 200 with a per-number result. One number failing does not fail the request; check each entry’s success.

Retries

The API does not retry for you and the SDKs do not either. Renting numbers spends money, so retry a 502 on a rent call only after checking GET /numbers/list. Waits are safe to repeat.