Troubleshooting

From what you're seeing to the error code behind it and the fix.

Find what you're seeing, then the fix. Each error's code is stable, and errors lists every one. When you contact support, include the error's request_id.

Creating payments

A create is refused because of its reference

409 reference_in_use

A reference names one live payment until it expires or you cancel it, and this one is taken by a payment for another amount or currency, or one that already received funds. The message names that payment. Cancel it with POST /payments/{id}/cancel and create again, or use a new reference.
A retried create made a second payment

Without a reference, every create makes a new payment. Send your order's ID as the reference, or an Idempotency-Key header, so a retry returns the first payment.
The business can't take payments yet

409 not_accepting

The business has no wallet that can receive, so checkout would have nothing to pay into. Finish setup in the dashboard: add the business, then create or connect its wallet.
expires_at is refused

400 invalid_request

expires_at must be an ISO 8601 date-time from 15 minutes to 30 days from now. Leave it out for 24 hours.

Checkout

Checkout asks for an email, or refuses to start without one

400 email_required

Card payments always need the customer's email, and crypto ones do too while checkout collects emails, which is on by default in Settings, under Checkout. Set customer_email when you create the payment and checkout won't ask, or send email when you create a checkout yourself.
The payment's page says it's already paid

409 payment_paid

Funds already reached the payment: it's succeeded, underpaid or needs_review, so it can't start another attempt. Check its status, and request the rest or accept it if it's short.
The payment's page says it expired or was canceled

410 payment_expired

A payment past its expires_at, or one you canceled (409 payment_canceled), can't be paid. Create a new one: its reference is free again.
A customer can't pay you at all

403 customer_blocked

You blocked the customer with that email. Unblock them in the dashboard, or with PATCH /customers/{id} and blocked: false.
A card checkout is refused for its price

400 amount_out_of_range

Cards take $5 to $10,000. Outside that range, customers pay with crypto.

Underpayments

Requesting the rest is refused

409 remainder_unavailable

The underpaid quote is still live, so the customer can send the rest to the same address. The message says until when, and gives the checkout URL to send them back to. Try again once it expires.
Nothing is left to request

409 nothing_due

The rest already arrived, or what arrived covers the price. Check the payment's status.
The wallet can't collect the rest

409 not_accepting

Your wallet no longer receives on the network the customer paid on, such as an external wallet that left it out. Add that network back, or accept what arrived.

Keys and requests

Every request is refused

401 invalid_api_key

Send Authorization: Bearer and a secret key, starting 402s_. Publishable keys and revoked keys can't authenticate.
The key works, but not for this business

403 business_forbidden

A key acts only as its own business. Leave out the 402pay-Business header.
A restricted key is refused

403 permission_denied

The key needs read on the resource for GET, and write for anything else. Embedding with include=customer also needs read on customers.
A body is refused before it's read

415 unsupported_media_type

Send Content-Type: application/json with every request that has a body.
A request comes back 405 with an empty body

The path exists but doesn't take that method, such as DELETE on a payment. Check the endpoint's page for the methods it takes.
A retry with the same idempotency key is refused

409 idempotency_key_reused

The key was already used for a different request. Use a new random key for each operation, and the same one only to retry it.
Requests are being turned away

429 rate_limited

Too many requests came from one IP address. Wait for the Retry-After seconds.

Lists

The next page is refused

400 invalid_request

A cursor only works with the list and filters it came from, and names the last item of the page before. If the filters changed or that item is gone, start again without cursor.

Webhooks

An endpoint URL is refused

400 invalid_request

It must be a public https:// address. localhost, private networks and link-local addresses are refused.
Deliveries never reach the server

Read each attempt, with your server's answer, in the dashboard or with GET /webhook-deliveries. The endpoint must be turned on, subscribed to the event type and reachable over public HTTPS. A local 402pay records deliveries without sending them. See troubleshooting webhooks for signatures that fail and events that arrive twice.