Error Codes
Every error response has an HTTP status and, on most endpoints, an error message meant for humans. Newer endpoints also return a stable, machine-readable code field — check the status first if a response doesn't have one yet.
Response shape
{
"error": "Minimum amount is $5",
"code": "MIN_TOPUP_AMOUNT"
}HTTP status codes
| Status | Meaning |
|---|---|
| 400 | Bad request — missing or malformed input |
| 401 | Missing, invalid, or expired authentication (Bearer key or session) |
| 402 | Insufficient balance for the requested operation |
| 403 | Authenticated but not allowed — e.g. not a reseller, or accessing another account's resource |
| 404 | Resource not found |
| 409 | Conflict — e.g. email already registered, domain already claimed by another account |
| 422 | Validation error — a field failed validation |
| 429 | Rate limit exceeded — see the endpoint's documented limit in the API Reference |
| 500 | Something went wrong on our end — safe to retry |
| 502 | A dependency (DNS lookup, upstream provider) failed — safe to retry |
| 503 | That feature is not configured / temporarily unavailable |
Machine-readable code values
Prefer matching on code over parsing the error text — the text may be reworded, the code won't change.
| Code | Meaning |
|---|---|
| UNAUTHORIZED | No valid session or API key on the request |
| FORBIDDEN | Authenticated, but not allowed to do this |
| USER_NOT_FOUND | The authenticated user no longer exists |
| NOT_FOUND | Generic resource-not-found |
| RATE_LIMITED | Too many requests — back off and retry after the window in X-RateLimit-Reset |
| INTERNAL_ERROR | Unexpected server error — safe to retry, contact support if it persists |
| INSUFFICIENT_BALANCE | Your balance doesn't cover this purchase |
| NO_NUMBERS_AVAILABLE | No stock for that service+country combination right now |
| MIN_TOPUP_AMOUNT | Top-up amount is below the minimum (varies by region — see the response for the exact figure) |
| CARD_NOT_CONFIGURED | Card payments are currently disabled — try crypto instead |
| CARD_CHECKOUT_FAILED | Creating the card checkout session failed — safe to retry |
| CRYPTO_INVOICE_FAILED | Creating the crypto invoice failed — safe to retry |
| CRYPTO_NOT_REFUNDABLE | This crypto transaction isn't eligible for a refund |
| RESET_PW_MISSING_FIELDS | Password reset request is missing a required field |
| RESET_PW_INVALID_TOKEN | The reset token is invalid or has expired — request a new one |
| FORGOT_PW_SEND_FAILED | Sending the reset email failed — safe to retry |
| CONTACT_MISSING_FIELDS | Contact form submission is missing a required field |
| CONTACT_CAPTCHA_FAILED | Turnstile verification failed on the contact form |
| CONTACT_SEND_FAILED | Sending the contact message failed — safe to retry |
Reseller-specific
The reseller API mostly uses HTTP status directly rather than a code field — see Reseller API Reference. One to note specifically:
| Status | Where |
|---|---|
| 409 | PATCH /reseller/profile — the customDomain you're setting is already configured on a different account. See White-Label & Custom Domain. |