Handle API errors and retry safely

Use the HTTP status, response body's success signal and request ID to handle failures without accidentally repeating a chargeable or destructive operation.

Read the failure response

Most API endpoint failures use this shape:

{
  "success": false,
  "error": "Invalid request"
}

Treat error as a message for diagnosis, not as a stable machine-readable code unless the endpoint reference says otherwise. Some endpoint-specific responses add structured errors or partial results.

For an endpoint response that contains success, require both a successful HTTP status and success: true. Treat success: false as a failed operation even if the HTTP status is 2xx.

Token requests and bearer-token validation use an OAuth-style envelope instead:

{
  "error": "invalid_token",
  "error_description": "invalid token"
}

Branch on the endpoint, HTTP status and response envelope. Do not require success on a token error.

Use the status and body together

The table describes the intended meaning of common non-2xx statuses. Status alone is not currently a universal success signal, so also inspect success or the OAuth error fields described above.

Status	Meaning	Action
`400`	The request is invalid.	Correct the fields, types or query parameters before trying again.
`401`	Authentication failed.	Request a valid access token or correct the credentials.
`403`	The organisation cannot perform the operation.	Check eligibility or permissions; do not retry unchanged.
`404`	The route or resource is unavailable to the caller.	Check the method, v1.1 path, identifier and resource ownership.
`409`	The request conflicts with current state.	Read the endpoint-specific error and resolve the conflict first.
`5xx`	cloudnumbering or an upstream service could not complete the request normally.	Apply the retry rules below and preserve the original request details.

Capture X-Request-Id when the response includes it. Also record the UTC time, method, path and status without logging credentials, message content or complete phone numbers.

Decide whether a request is safe to retry

An HTTP timeout or disconnected connection is an unknown outcome. It does not prove that the server rejected the request.

Retry read-only GET requests after temporary connection failures or 5xx responses, using bounded exponential backoff with jitter.
Treat a 2xx response with success: false as an endpoint failure. Read its error and do not retry it blindly.
Do not retry 400, 401, 403, 404 or 409 unchanged.
Retry a state-changing request only when its endpoint documents idempotent behavior or accepts an idempotency key that you supplied with the original request.
Keep the same idempotency key and exactly the same request content for a retry. A new key represents a new operation.
Stop after a bounded number of attempts and surface the unresolved outcome to an operator.

cloudnumbering does not currently publish a general rate-limit or retry schedule. Do not invent fixed retry delays or assume that every POST, PUT or DELETE is idempotent.

Handle common unknown outcomes

Sending an SMS

POST /v1.1/sms does not accept an idempotency key. If the connection fails after sending the request, do not automatically submit it again: the first request may have created and charged for a message.

Save result.sid whenever a successful response arrives. Use it to correlate delivery receipts.

Creating a number order

POST /v1.1/orders does not accept an idempotency key. Previewing an order is read-only, but creating the order can allocate numbers and charge the account balance.

After an unknown create outcome, inspect recent orders, assigned numbers and the organisation's balance. Those checks may not prove whether one particular request completed. Do not retry automatically; contact support if the outcome remains uncertain.

Creating port-in requests

Each entry sent to POST /v1.1/porting/in can include an idempotencyKey UUID. Generate the key before the first attempt, store it with the intended request and reuse it only for the identical entry. The response can contain both created or reused orders and per-entry errors, so inspect every result.

See the port-in endpoint reference for the complete contract.

Reconnecting numbers

POST /v1.1/numbers/reconnect accepts an idempotencyKey UUID. Reconnecting is chargeable and state-changing, so generate the key before the first attempt, store it with the intended request, and reuse exactly the same key and body when retrying after an unknown outcome.

Updating the voice IP allowlist

Adding an IP that is already present and removing an IP that is already absent are documented as successful idempotent operations. This guarantee applies to those endpoints, not to every endpoint update.

Escalate an unresolved failure

If the outcome is still unknown, keep the original request body in a secure system and contact support with:

the UTC time;
HTTP method and path;
status and safe error text;
X-Request-Id, when present;
the relevant resource SID or idempotency key, without access tokens or client secrets.