Limits & Errors
Phone number limits for buying, KYC, porting and Branded Calling, what a number cannot do, and the errors you will meet, each with its fix.
Limits
| Limit | Value |
|---|---|
| Price | $3 to $30 per number per month, charged in full at activation and on the 1st of each month, with no proration |
| Number cap | Your profile limit; none where profiles are unlimited |
| One number per profile | A purchase on a profile that already holds a number goes to the next free profile |
| Purchase velocity | A second purchase within 10 minutes needs allowMultiple: true |
| Search results | limit defaults to 20, at most 100 |
| Stock snapshot | inStock and area counts refresh every 6 hours |
| Stock watches | At most 20; one per country and number type; consumed when it fires |
| KYC review | The number activates within 1 to 3 business days |
| KYC quantity | 1 to 5 same-country numbers per verification; a pre-order is 1 |
| Pre-order sourcing | Usually 2 to 4 weeks, not guaranteed; nothing billed until active |
| Reviewer response | Up to 5 attachments (PDF, JPG, PNG or WebP), 10 MB each |
| Hosted KYC link | Single use, valid 7 days |
| Port-in documents | PDF, JPEG or PNG, up to 10 MB; unattached documents are deleted after 30 minutes |
| Port-in drafts | Cancelled automatically after 14 days abandoned |
| Port-in timing | US/CA a few business days (same day for FastPort); international several weeks |
| Branded Calling identity | displayName 1 to 35 characters; 1 to 10 callReasons of up to 64 characters; lasts one year |
| Branded Calling numbers | Up to 15 per attach call, up to 100 per detach call; one identity per number |
What you cannot do
Phone numbers on Zernio do not allow:
- Connecting WhatsApp to a toll-free number
- Buying one exact
phoneNumberin a regulated country or type - SMS outside the SMS-capable countries, or on a number that is not SMS-capable
- Enabling SMS or Calls on WhatsApp numbers you brought through embedded signup
- Porting Spanish, German, French or Dutch mobiles, or porting outside the supported countries
- Porting numbers from several non-US/CA countries in one request
- Pre-ordering a country or type that does not require KYC
- Undoing a release (the number returns to the carrier pool)
- Emergency (112/911) calls
- WhatsApp outbound calling in the US, Canada, Egypt, Vietnam and Nigeria
- Branded Calling outside US numbers, or for businesses outside the US and Canada
- Branded Calling display on landlines, international destinations or other number types
- One caller identity for several businesses
- Re-attaching a number the carrier marked
permanently_rejected - Deleting a caller identity while a claim is open against it
Common errors
| Status | Code | Cause | Fix |
|---|---|---|---|
400 | The country is not offerable | Pick a code from GET /v1/phone-numbers/countries | |
400 | A search parameter the endpoint does not know | Use one of the parameters the error lists | |
400 | phoneNumber set on a regulated country or type | Omit phoneNumber and run the KYC flow | |
400 | numberType: "toll_free" with the default connectWhatsapp: true | Send connectWhatsapp: false | |
400 | A purchase past the number cap | Release a number, or raise your profile limit | |
402 | PAYMENT_REQUIRED | No payment method on file | Add a card, then retry with the same purchaseIntentId |
422 | USAGE_BILLING_REQUIRED | The team is not on usage-based billing | Move the workspace to usage-based billing |
409 | AREA_CODE_UNAVAILABLE | The areaCode has no deliverable inventory | Pick another area, or omit it |
409 | PHONE_NUMBER_UNAVAILABLE | The phoneNumber you picked is gone, or WhatsApp rejected it | Search again and pick another |
409 | NO_WHATSAPP_ELIGIBLE_NUMBER | Every number offered is one WhatsApp refuses | Pass an areaCode, or retry for a fresh batch |
409 | PURCHASE_VELOCITY | A second purchase within 10 minutes | Pass allowMultiple: true |
409 | invalid_resource_state | Releasing a number attached to a SIP trunk | Detach it first |
409 | A stock watch for a country in stock, or a 21st watch | Buy instead, or cancel a watch | |
400 | A KYC value failed validation, often an address outside the country or a file over the limit | Run POST /v1/phone-numbers/kyc/validate-address first | |
409 | area_pre_order_available | The address area has no stock but can be pre-ordered | Resend with preOrder: true once the customer agrees |
409 | area_code_unavailable | The area has no inventory and cannot be pre-ordered | Pick another area or set a stock watch |
409 | country_out_of_stock | Nothing deliverable in the country and type, and no pre-order | Set a stock watch |
409 | reuse: true with no approved verification on file | Submit the full KYC form | |
422 | A port-in number is not portable, the numbers span several non-US/CA countries, or every split order failed | Check each number and submit one country per request | |
409 | A port-in number is already on Zernio or in an in-flight port | Drop it from the request | |
422 | feature_not_available | A Branded Calling business outside the US or CA, or a number that is not an active US number | Use a US or Canadian business and active US numbers |
409 | invalid_resource_state | The caller identity is not in a status that allows the action | Check the identity's status first |
400 | The authorizer's 6-digit code is wrong or expired | Request a new code | |
403 | usage_billing_required | Creating a caller identity without usage-based billing | Move the workspace to usage-based billing |
A KYC decline leaves the number in regulatory_declined; fix it with remediation.
Every error uses the envelope in error handling.
Related
- Availability & Pricing: countries, types, stock and capabilities.
- Buying a Number: search, purchase and release.
- KYC: regulated countries and pre-orders.
- Porting: bring a number you own.
- Branded Calling: your name and logo on US calls.
Was this page helpful?
Branded Calling
Show your business name, logo and reason for calling on the callee's phone: register the business, create a caller identity, pass vetting, then attach your US numbers.
Voice & Calls
Receive and place phone (PSTN) calls on your numbers, route inbound calls to a phone, a SIP endpoint or an AI voice agent, and read every call from one history.