# Error catalog

> Browse step-by-step guides for Payments AI API errors: what each error code means, why it happens, and how to resolve it.

API errors include a `docUrl` field linking to these guides. Slugs are derived from the machine-readable `code` field (`.` and `_` → `-`).

## Documented errors

- [Invalid credentials](/errors/invalid-credentials) — `invalid_credentials` (401)
- [User not confirmed](/errors/user-not-confirmed) — `user_not_confirmed` (401)
- [Product not found](/errors/product-not-found) — `product.not_found` (404)
- [Product archived](/errors/product-archived) — `product.archived` (422)
- [Product not in draft](/errors/product-not-draft) — `product.not_draft` (409)
- [Product or plan values rejected](/errors/product-provider-rejected) — `product.provider_rejected` (422)
- [Plan amount out of range](/errors/plan-amount-out-of-range) — `plan.amount_out_of_range` (400)
- [Plan billing interval too long](/errors/plan-billing-period-too-long) — `plan.billing_period_too_long` (400)
- `request.numeric_out_of_range` (400) — a number in the request is too large to store. Lower the amount, price or quantity; retrying the same request will not help.
- `product.name_contains_markup` (400) — the product name contains an HTML-like tag such as `<b>` or `<Beta>`. The `errors` entry for `name` says how to fix it; use parentheses instead of angle brackets, e.g. `Pro (Beta)`.
- [Checkout plan not found](/errors/checkout-plan-not-found) — `checkout.plan_not_found` (404)
- [Transaction not found](/errors/transaction-not-found) — `transaction.not_found` (404)
- [Transaction not refundable](/errors/transaction-not-refundable) — `transaction.not_refundable` (422)
- [Refund exceeds available balance](/errors/transaction-refund-insufficient-funds) — `transaction.refund_insufficient_funds` (400)
- [Merchant not found](/errors/merchant-not-found) — `merchant.not_found` (404)
- [Merchant not linked](/errors/merchant-not-linked) — `merchant.not_linked` (400)
- [Company provisioning failed](/errors/company-provisioning-failed) — `company_provisioning_failed` (409)
- [Business name already in use](/errors/business-name-taken) — `business_name_taken` (409)
- [Email cannot receive mail](/errors/email-undeliverable) — `email_undeliverable` (400)
- [Invoice not found](/errors/invoice-not-found) — `invoice.not_found` (404)
- [Customer not found](/errors/customer-not-found) — `customer.not_found` (404)
- [API key not found](/errors/api-key-not-found) — `api_key.not_found` (404)
- [Webhook destination not found](/errors/webhook-destination-not-found) — `webhook_destination.not_found` (404)
- [Webhook URL forbidden](/errors/webhook-destination-url-forbidden) — `webhook_destination.url_forbidden` (400)
- [Discount code not found](/errors/discount-code-not-found) — `discount_code.not_found` (404)
- [User not found](/errors/user-not-found) — `user.not_found` (404)
- [User already a team member](/errors/team-already-member) — `team.already_member` (409)
- [Team role forbidden](/errors/team-role-forbidden) — `team.role_forbidden` (403)

## MCP authentication

Returned by the MCP endpoint (`/api/mcp`) with HTTP 401. The `WWW-Authenticate` header still carries the OAuth discovery challenge.

- [Missing MCP token](/errors/missing-token) — `missing_token` (401)
- [Invalid MCP token](/errors/invalid-token) — `invalid_token` (401)
- [MCP token expired](/errors/token-expired) — `token_expired` (401)
- `token_validation_unavailable` (401) — the token could not be checked because the backend is unavailable. Retry in a moment; do not generate a new token.

## OAuth device authorization

Returned by the dashboard approval page for a device authorization ([Connect without a terminal](https://doc.mor.payments.ai/connect#connect-without-a-terminal)). The OAuth endpoints themselves answer with an RFC 6749 `{ "error", "error_description" }` body instead.

- [Device code not accepted](/errors/oauth-device-user-code-rejected) — `oauth.device_user_code_rejected` (403)
- [Device approval request closed](/errors/oauth-device-request-expired) — `oauth.device_request_expired` (403)
- [Device approval already answered](/errors/oauth-device-request-decided) — `oauth.device_request_decided` (403)
- [Device approval belongs to another account](/errors/oauth-device-request-forbidden) — `oauth.device_request_forbidden` (403)
- [OAuth scope not supported or not offered](/errors/oauth-invalid-scope) — `oauth.invalid_scope` (400)

## How docUrl works

`https://doc.mor.payments.ai/errors/{slug}` — e.g. `product.not_found` → `/errors/product-not-found`
