Errors

Every JSON response carries success. Failures use one format everywhere:

{
  "success": false,
  "error": {
    "code": "insufficient_balance",
    "message": "The balance is too low for this request.",
    "details": { "balance": 0.02, "required": 0.15 }
  }
}

code is a stable snake_case string. Branch on it, not on message.
message is for people and may change.
details is present when there is something structured to say, for example the offending fields of a validation_error (details.issues) or the current version in a metadata_version_mismatch.

The SDKs turn each code into a typed exception: Node.js and PHP.

Two things that are not errors

A wait that found nothing. The waiting calls (GET /numbers/sms/wait, GET /emails/wait) answer 200 with { "success": false, "error": { "code": "wait_timeout" } } when the wait time ends. Ask again. See Waiting for results.
A captcha that was not solved. POST /captchas/resolve returns 200 with a status of solved, failed or timeout. failed and timeout are free. See Solving captchas.

Common codes

Status	Code	Meaning
400	`validation_error`	The request does not match the schema. `details.issues` lists the fields.
400	`invalid_service_timeout`	`X-Service-Timeout` is not a positive integer.
400	`invalid_regex`	`match_regex` or `code_regex` does not compile. `details.param` names the parameter.
400	`invalid_cursor`, `invalid_limit`	Bad pagination input.
400	`invalid_metadata`, `invalid_if_match`	Bad metadata patch or `If-Match` header.
401	`missing_api_key`, `invalid_api_key`	See Authentication.
402	`insufficient_balance`	The balance does not cover the request. Nothing was done or charged.
402	`spend_limit_exceeded`	A daily or monthly spend limit would be exceeded. `details` names the scope and period.
403	`team_suspended`, `email_not_verified`	See Authentication.
404	`not_found`	Unknown path or resource.
412	`metadata_version_mismatch`	`If-Match` is stale. `details.current_version` is the current one.
413	`metadata_too_large`, `payload_too_large`	Body over the limit.
429	`rate_limited`	Too many requests.
500	`internal_error`	Unexpected failure. Safe to retry reads.

Numbers

Status	Code	Meaning
400	`service_required`, `phone_number_required`, `country_not_supported`, `invalid_filter`	The request is missing something the number type needs.
404	`number_not_found`	The number is not in your project.
409	`no_numbers_available`	Nothing in stock for this request right now.
409	`number_unavailable`	The chosen number was taken. Pick another.
409	`max_price_too_low`	`max_price` is below the catalog price. `details.price` is the catalog price.
409	`number_not_active`	The number was already released or has expired.
409	`release_too_early`	The number cannot be released yet. `details.retry_after_seconds` says when.
409	`resend_not_supported`	Only `temporary` numbers can request the SMS again.
502	`upstream_error`	The upstream supplier failed. Retry.
503	`supply_unavailable`	No supplier can serve the request right now. Retry shortly.

Emails

Status	Code	Meaning
400	`invalid_timestamp`	`timestamp` is not a number.
400	`invalid_return_url`	The `return_url` origin is not in the project’s allowed origins.
400	`invalid_branding`, `invalid_provider`, `provider_not_allowed`	Bad authorization link input.
400	`invalid_email_address`, `domain_not_available`	Bad Cloudflare address.
404	`email_account_not_found`, `attachment_not_found`, `auth_link_not_found`, `oauth_result_not_found`	Unknown resource.
409	`email_account_exists`, `email_account_in_use`	The address is already connected.
410	`auth_link_expired`, `auth_link_revoked`, `auth_link_exhausted`	The authorization link can no longer be used.
503	`platform_unavailable`	Connecting this kind of mailbox is not available right now.

Captchas

Status	Code	Meaning
400	`unsupported_request`	No solver can handle this type, field and `mode` combination.
500	`price_unavailable`	The type has no active price.
503	`provider_unavailable`	Nothing can solve the request right now, for example `mode: "browser"` without a connected browser worker. Retry shortly.

Webhooks

Status	Code	Meaning
404	`webhook_endpoint_not_found`, `webhook_delivery_not_found`	Unknown resource.
409	`webhook_endpoint_limit`	A project can have 20 endpoints.
409	`webhook_endpoint_disabled`	The endpoint is disabled. Enable it first.
409	`webhook_delivery_not_failed`	Only failed deliveries can be retried.