> For the complete index of the 402pay docs, see [llms.txt](https://developer.402pay.co/llms.txt).

# 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](https://developer.402pay.co/api/errors.md) 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`](https://developer.402pay.co/api/payments/cancel.md) 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}`](https://developer.402pay.co/api/customers/update.md) 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](https://developer.402pay.co/api/payments/accept.md).

## 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](https://developer.402pay.co/guides/webhooks.md#troubleshooting) for signatures that fail and events that arrive twice.