Errors and status codes

What each HTTP status means across the API, and the error body you get back.

Every error is JSON with status: "error" and a human-readable error message. Some errors add fields (for example current_plan, generated_message or refunded); each endpoint’s Errors section lists them.

{ "status": "error", "error": "insufficient wallet balance" }

Status	Meaning
200 / 201 / 202	Success. 201 = created. 202 = accepted and finishing in the background.
400	Invalid request: validation failed, a malformed UUID, or a missing required field.
401	Missing or invalid API key. See Authentication.
402	Insufficient wallet balance for an action that costs money (messages, AI messages, campaigns, review requests, phone number purchases). Nothing was charged.
403	Plan doesn’t include API access, a plan limit was reached (for example max_phone_numbers), or the key type is wrong for this endpoint.
404	Not found in this sub-account (or agency). Also returned for ids that belong to another tenant.
409	Conflict: a duplicate, a resource in the wrong state, a delete that would cascade without force, or an Idempotency-Key reused with a different body.
429	Rate limit exceeded. Wait for the number of seconds in Retry-After. See Rate limits.
500 / 502 / 503	Server or upstream provider error. Reads are safe to retry. For writes, check the resource’s state first, or use an idempotency key where the endpoint supports one.

Retrying

• 429: wait Retry-After seconds, then retry the same request.
• 5xx on a read: retry with backoff.
• 5xx on a write: only phone number purchases are safe to retry blindly. For everything else, read the resource back before retrying.

The Node SDK throws typed errors (CenterfyNotFoundError, CenterfyRateLimitError, …) and can retry 429/5xx automatically with maxRetries.