Errors & limits
Understand response errors and the limits shared by your account.
Read error responses
Failed requests return an HTTP status and a JSON error message. Record the status, message and order ID where available, without logging credentials.
A successful HTTP status does not replace checking order.status. Allocation failures and unresolved purchases may be represented in an order response.
{
"error": "Insufficient balance. Top up your wallet to buy this number."
}HTTP status reference
400: invalid parameters, JSON or UUID v4 idempotency key. Correct the request.
401: missing, invalid, revoked or expired API key. Check Bearer authentication.
402: insufficient wallet balance. Top up in the dashboard.
404: unknown endpoint or an order that does not belong to your account.
409: expired quote, unavailable stock, conflicting retry or an invalid order action. Read the message and retrieve an existing order before retrying.
413: SMS JSON request body exceeds 16 KiB.
429: request rate or account limit. Honor Retry-After; longer account limits may apply.
503: temporary service unavailability. Keep the same purchase idempotency key when recovering an uncertain request.
Account limits
60 API requests per minute per customer, shared across all of that customer's API keys.
120 quotes per hour and 30 purchases per hour, shared with the website. Up to 10 active or unresolved orders at one time.
Quotes expire in two minutes. Poll active orders every 10 seconds. Order history returns up to 20 records per page.
There is no limit on the number of API keys you can create. Creating more keys does not bypass customer-level limits.
Get help with an unresolved order
Open a support ticket from your dashboard with the order ID, HTTP status and error message. Include a redacted screenshot if it helps explain the issue.
Never send your API key. For purchase_unknown or refund_review, avoid automatically buying another number while support reviews the original order.