Payment method required
What a 402 payment_required response means, which requests trigger it, and how the user adds a card without leaving the dashboard.
Some actions cost money from the moment they succeed, so Zernio checks for a card on file before it runs them. When there is none, the request returns 402 with code: "PAYMENT_REQUIRED" and nothing is created. Send the user to dashboard_url, let them add a card in the billing drawer, and retry the request.
Which requests return 402
| Request | reason | Why |
|---|---|---|
Connecting a third social account (GET /v1/connect/{platform}, POST /v1/connect/whatsapp/embedded-signup, Discord, Slack and Bluesky connect) | free_tier_exceeded | The first 2 connected accounts are free; every further account bills per day of connection. |
| Connecting the first X account | twitter_passthrough | X bills every API call and Zernio passes that cost through, so a card is needed before the first X account, even inside the free tier. |
| Buying a phone number, submitting phone-number KYC, registering a sender ID or a 10DLC brand | none | These responses carry code and error only, no reason, details or dashboard_url. Treat them like free_tier_exceeded and send the user to https://zernio.com/dashboard/billing?add_payment_method=1. |
| Any connect request on an enterprise contract that has reached its negotiated account cap | enterprise_required | Not a card problem: the contract's limit has to be raised. |
The API reference lists 402 on every operation that can return it.
The response
{
"error": "Add a payment method to connect more than 2 accounts.",
"code": "PAYMENT_REQUIRED",
"reason": "free_tier_exceeded",
"documentation_url": "https://docs.zernio.com/billing/payment-method-required",
"dashboard_url": "https://zernio.com/dashboard/billing?add_payment_method=1",
"details": {
"free_tier_account_limit": 2,
"current_account_count": 3,
"has_payment_method": false
}
}reason is the value to switch on. details carries the numbers behind the message: free_tier_account_limit and current_account_count for the free tier, has_payment_method for both card reasons, and effective_account_limit for enterprise_required.
What to do
For free_tier_exceeded and twitter_passthrough, open dashboard_url for the user. It lands on the Zernio billing page with the add-payment-method drawer already open: card details (or Apple Pay, Google Pay and Link where available), the billing address for invoices, and an optional VAT or tax ID. Nothing is charged when the card is added; usage bills at the end of the period as described on the billing page. Once the drawer reports the card as saved, repeat the original request and it goes through.
The same drawer opens by itself when the user hits one of these gates inside the Zernio dashboard, and the action they were doing (connecting the account, buying the number) continues once the card lands. A team member can add the card too; it is attached to the team owner's billing profile.
For enterprise_required, dashboard_url points at the enterprise contact page instead. The team already has a card; the connected-account limit on its contract is what needs to change.
If the card is declined
A declined card stays in the drawer with the bank's message next to the card number; the user edits the number or tries another card and nothing is saved until one is accepted. A billing address that Stripe cannot match to a tax location is rejected in the drawer as well, so invoices can always be issued against the address on file.
Related
- Billing: when the card is charged, proration and the graduated ladder.
- Pricing: the rates and the $12 monthly credit.
- Get billing: the team's balance and payment status, including whether access is currently payment-blocked.