# Errors

Building with an AI agent? Start at https://docs.payme.io/agents.md

## Related

- [Idempotency and Retries](/payments/getting-started/idempotency-and-retries)
- [Environments](/payments/getting-started/environments)
- [Test Cards and Payment Methods](/payments/getting-started/test-cards-and-payment-methods)
- [Sale Statuses](/payments/codes-statuses/sale-statuses)
- [Quickstart](/payments/getting-started/quickstart)

## Error response shape

```json
{
  "status_code": 1,
  "status_error_details": "Seller was not found",
  "status_additional_info": "seller_payme_id",
  "status_error_code": 251
}
```



| Field | Meaning |
|-------|---------|
| `status_code` | `0` success, `1` error.  |
| `status_error_code` | PayMe's numeric error code. `0` on success.  |
| `status_error_details` | The error message, in the language you asked for.  |
| `status_additional_info` | Extra detail — usually the name of the field at fault. Alternatives are joined with ` / `, for example `seller_payme_id / seller_id`.  |
| `payme_status` | `success` or `error` (on some responses and on the return-URL redirect).  |

Error bodies also include a `session` field. 

## HTTP status vs `status_error_code`

The two numbers are separate: `status_error_code` is never used as the HTTP status.

| Situation | HTTP status |
|-----------|-------------|
| Card declined (codes `20xxx` / `21xxx`) | **200**, with `status_code: 1` |
| Most request errors — for example missing parameter (`1`), unknown client key (`200`), unknown seller (`251`), wrong sale status (`305`) | **500** |
| Some access and input errors | 400, 403 or 422 |
| Too many requests, or a duplicate call still running (`998`) | 429 |
| Service temporarily read-only | 503 |



**Decide what happened from `status_code` and `status_error_code`, not from the HTTP status.** A `200` can be a decline. A `500` with `status_code: 1` and an error code is a refusal: your request usually needs fixing, and it doesn't mean PayMe is down.

In a few cases the outcome is **unknown**, and PayMe may have acted. Check the sale before repeating a call that moves money ([how](/payments/getting-started/idempotency-and-retries#before-retrying-check-the-sale)):

- codes `991` and `20002`, at any HTTP status: contact was lost part-way, and the sale can show `failed` even so. Code `999` gives no information;
- HTTP 429 (`998`): this call was turned away, but a matching call may still be running;
- a timeout, a dropped connection, a body that isn't JSON, a gateway error page, or a body with no error code.

## Getting messages in English

If you omit `language`, messages come back in **Hebrew**. Send `"language": "en"` on every call. `he` and `en` are fully supported; `es`, `ru` and `ar` are accepted, but messages and the payment page are then mostly in English. Values are case-insensitive. Any other value, or an empty string, returns error `51`. 

A few very early errors, such as a malformed key format, may still come back in Hebrew. 

## Common error codes

The tables below cover the codes integrators meet most often.

### Request and credential errors

| Code | Meaning | What to do |
|------|---------|------------|
| `1` | Required parameter is missing. `status_additional_info` names it. Also returned when no client key and no seller key are sent. | Add the named field. |
| `10` | `installments` or `market_fee` is not numeric | Send a number such as `1` or `"1"`. |
| `19` | Please provide all required fields (some endpoints) | Check the endpoint's required fields. |
| `20` | Validation error. Also "Merchant-Seller inconsistency" (HTTP 400): the seller belongs to a different partner from the `payme_client_key` sent. Also "<field> contains invalid data" (HTTP 400): on `generate-sale`, `pay-sale`, `capture-buyer-token`, `POST /sales`, `pay-subscription` and `PATCH /subscriptions/{id}`, a field other than the card fields, `transaction_id` and `order_number` contains a 14–19-digit number that passes the card checksum. | Fix the fields listed in `status_additional_info`. Never put card-like numbers in descriptive fields. |
| `51` | Unsupported or empty `language` value | Use `he` or `en` (`es`, `ru` and `ar` are accepted but mostly shown in English). |
| `163` | "Account settings problem - please contact Customer Support": the MPL exists but is inactive, or a test MPL was sent to production | Check that `seller_payme_id` and the base URL are from the same environment; if they are, contact PayMe. |
| `200` | Merchant was not found (HTTP 500): the `payme_client_key` (or `PayMe-Partner-Key`) matches no partner, usually because a seller sent its own MPL there or a production key was sent to the sandbox. `status_additional_info` is `payme_client_key`. | A seller removes the field and authenticates with `seller_payme_id` alone; a partner checks the key and the environment. |
| `201` | The partner is inactive | Contact PayMe. |
| `251` | Seller was not found: the `seller_payme_id` / `seller_id` matches no seller. Also returned for an unknown public key during card tokenization. | Check the MPL or public key and the environment. |
| `252` | Currency not allowed for this account | Use a currency enabled on the account. |
| `312` | More than 1 installment in a non-ILS currency | Installments are available for ILS sales only. |
| `351` | `installments` outside the accepted ranges, or more than one installment with a payment method other than `credit-card`, `multi` or `pos` | Send `1`–`12`, or `102`–`112` to let the buyer choose. Installments are for card payments only. |
| `358` | ILS price lower than the number of installments | Raise the price or lower the installments. |
| `352` | `sale_price` is missing, not numeric or outside the allowed range. On `capture-sale`, also `0` or more than the authorization allows | Send minor units within the allowed range. |
| `353` | `product_name` is missing | Add `product_name`. |
| `357` | Invalid sale type: `sale_type` is not one of `sale`, `authorize`, `token`, `seller-token`, `credit`, `template`, `multi-capture`, or it can't be combined with the request (for example `multi-capture` with `buyer_key`). `status_additional_info` holds the value sent. | Send a listed value. For recurring payments, create a subscription with `generate-subscription` (see [Recurring Payments](/payments/saved-cards-recurring)). |
| `24` | Unknown `sale_payment_method` value | Use a value from [Available Payment Methods](/payments/wallets-apms). |
| `320` | The currency isn't supported for this payment method: BACS needs GBP, SEPA needs EUR, and an Israeli direct debit charge needs ILS | Send the method's currency. |
| `368` | `sale_payment_method` was sent as an array (HTTP 400) | Send one value, as a string. |
| `601` / `602` / `606` | `buyer_key` combined with `capture_buyer` (`601`), a `token` or `seller-token` sale type (`602`), or `template` (`606`) | Charge a saved token with `sale_type` `sale` or `authorize`. |
| `608` | `buyer_perform_validation: true` without `capture_buyer` or a token sale | Send it only when you capture a token. |



### Sale-state, retry and rate-limit errors

| Code | Meaning | What to do |
|------|---------|------------|
| `305` | Cannot perform action due to an incorrect status. `status_additional_info` holds the sale's current status. Returned, for example, when a paid sale is paid again or a fully refunded sale is refunded again. | Check the sale with `get-sales`; do not retry. |
| `517` | The refund amount is bigger than the sale's price | Refund no more than the sale's price, less what you already refunded. |
| `991` | A network problem, part-way through | The outcome is unknown. Check the sale, and quote `session` to PayMe. |
| `20002` | A network problem reaching the card company | The outcome is unknown. Check the sale, and quote `session` to PayMe. |
| `999` | No information provided | The outcome is unknown. Check the sale, and quote `session` to PayMe. |
| `998` | HTTP 429. Either "Too Many Attempts." (rate limit) or "Duplicated action detected, please retry later" (the same action on the same sale is still running). Tell them apart by `status_additional_info`; `status_error_details` is "Operation is not permitted" in both. | Wait (`Retry-After` header) and check the sale before retrying. |



### Codes PayMe support sees most often

The cases below come from PayMe's support knowledge base; the fix is what support will ask you to check first. 

| Code or message | Usual cause | What to do |
|-----------------|-------------|------------|
| `251` / `ERR-020` "seller not found" | Wrong MPL, or a test key sent to the production URL (or the reverse) | Copy the MPL from the dashboard (**Admin → API & Integration**) and check that key and base URL belong to the same environment. |
| `130` "Seller is over sale limit, unable to create new sales" | This sale would take the seller over its processing limit | Complete any pending verification in the dashboard, then ask <partners@payme.io> to review the seller's processing limit (send `seller_payme_id`). |
| `720` service not activated | Apple Pay, Google Pay, Bit, B2B transfers or another value-added service is not enabled on the account | A seller installs Apple Pay, Google Pay or Bit itself from the dashboard app store (חנות אפליקציות); the method is active as soon as it is installed. A partner enables it for its seller with `vas-enable`. For B2B transfers and other services, ask <partners@payme.io> (give your MPL). |
| `603` from `get-buyer-key` | You sent `seller_payme_id` to read an account-level token (one captured without `buyer_is_private`). Only `get-buyer-key` returns `603`; charging an account-level token works for any seller of the same partner | Call `get-buyer-key` with `payme_client_key` instead, or capture new tokens with `"buyer_is_private": true`. A sandbox token works only on the sandbox, with sandbox credentials. |
| `357` "Invalid sale type: recurring" | `recurring` isn't a sale type | Recurring payments are subscriptions: create one with `generate-subscription` (see [Recurring Payments](/payments/saved-cards-recurring)). |
| `401` / `403` | Invalid credentials | Check the key against the environment it belongs to. There is no self-service key regeneration; a correct key that is still refused points at the account — contact PayMe. |
| Garbled Hebrew or `?` characters in responses | Request not sent as UTF-8, or fields containing Hebrew quotation marks (for example בע"מ) | Send UTF-8; test with an ASCII-only value to isolate the field. |
| "Merchant not allowed to use this buyer" | The token was captured at account level, not for this seller | Re-capture the card with `"buyer_is_private": true` on the capturing call (`generate-sale` with `capture_buyer`, or `capture-buyer-token`). |
| Callbacks not arriving | URL, firewall, slow reply or signature problems | Send `sale_callback_url` on every `generate-sale` (and `sub_callback_url` on `generate-subscription`); there is no dashboard callback setting for a seller; make the endpoint publicly reachable (no VPN or firewall); reply `200` within the timeout; verify the signature as described on [Callbacks](/payments/getting-started/callbacks). |

### Card declines

Declines return HTTP 200 with `status_code: 1`. Codes `21xxx` are card problems; `20xxx` are refusals from the card company or gateway. 

| Code | Message |
|------|---------|
| `20004` | Refusal by credit company. Please try a different card |
| `21001` | The card is blocked |
| `21002` | The card is stolen |
| `21004` | The card is expired |
| `21005` | Incorrect card number |
| `21006` | The credit limit has been reached |
| `21007` | CVV/ID is required but was not entered |
| `21008` | Incorrect CVV or ID |
| `21017` | 3D Secure authentication failed. The buyer didn't complete the challenge, or the issuer rejected it |



The sandbox test cards that produce each one are on [Test Cards and Payment Methods](/payments/getting-started/test-cards-and-payment-methods#credit-card-numbers-for-testing-specific-responses-and-errors).

### Bit

Bit requests end with their own codes. They are per-transaction outcomes, not account problems. 

| Code | Meaning | What to do |
|------|---------|------------|
| `23001` | The buyer rejected the Bit request | Let the buyer retry or choose another method. |
| `23002` | The Bit request was canceled | Retry. |
| `23003` | The Bit request expired before the buyer approved it | Retry, and ask the buyer to approve it in the Bit app straight away. |

### Setup, seller and saved-card errors

| Code | Meaning | What to do |
|------|---------|------------|
| [`21`](/agents/errors/error-21) | A callback or return URL was refused, often a local address. The whole call fails | Leave the field out when the address is local, or use a public one. |
| [`25`](/agents/errors/error-25) | Phone number refused | Send `seller_phone` in international format, such as `+972501234567`. |
| [`42`](/agents/errors/error-42) | A value that must be whole has decimals, for example `sale_price` on `capture-sale` | Send integer minor units. |
| [`114`](/agents/errors/error-114) | Business type doesn't fit the seller's details | Read the message. For sole proprietors, `seller_inc_code` must equal `seller_social_id`. |
| [`116`](/agents/errors/error-116) | `seller_birthdate` is unreadable, or the person is under 16 | Send `dd/mm/yyyy`. |
| [`118`](/agents/errors/error-118) | `seller_social_id_issued` is unreadable or in the future | Send `dd/mm/yyyy`. |
| [`121`](/agents/errors/error-121) | `seller_inc_code` isn't numeric | Send digits only. |
| [`174`](/agents/errors/error-174) | Not supported for this seller type, usually a partner's own MPL used on `generate-sale` | Use the seller's MPL. |
| `303` | "Could not access sale": the sale isn't this seller's or this partner's | Check `seller_payme_id`, `payme_client_key` and the sale ID. |
| [`304`](/agents/errors/error-304) | `market_fee` is negative (a non-numeric `market_fee` returns `10`) | Send a number from `0` to `60`. |
| [`308`](/agents/errors/error-308) | The fee is above 60% | Keep it at 60% or below. |
| `367` | The sale has expired, after its `sale_expiry_seconds` | Create a new sale. |
| [`420`](/agents/errors/error-420) | No connected terminal accepts this payment | If every card fails, no terminal is connected: ask PayMe. If only some payments fail, the account's terminals don't accept something in this one: the currency, the card brand, a foreign card, the amount, the number of installments, or the account's processing limit. Fewer installments or a currency the account allows can fix it; otherwise quote `session` to PayMe. |
| [`604`](/agents/errors/error-604) | The saved-card token is inactive, often a single-use token charged again | Capture the card again. |
| [`605`](/agents/errors/error-605) | The token doesn't belong to this seller | Charge it on a seller that can use it. |
| [`790`](/agents/errors/error-790) | The plan requires or refuses the field named in `status_additional_info`, often `seller_id` | Add or remove that field. |
| `907` | The seller is on an automatic withdrawal plan, so manual withdrawals aren't allowed | PayMe pays out on the plan's schedule. |

### Answers for common errors

These codes each have a page with causes and fixes: [`10`](/agents/errors/error-10), [`21`](/agents/errors/error-21), [`25`](/agents/errors/error-25), [`42`](/agents/errors/error-42), [`109`](/agents/errors/error-109), [`114`](/agents/errors/error-114), [`116`](/agents/errors/error-116), [`118`](/agents/errors/error-118), [`121`](/agents/errors/error-121), [`130`](/agents/errors/error-130), [`163`](/agents/errors/error-163), [`174`](/agents/errors/error-174), [`200`](/agents/errors/error-200), [`201`](/agents/errors/error-201), [`251`](/agents/errors/error-251), [`252`](/agents/errors/error-252), [`304`](/agents/errors/error-304), [`305`](/agents/errors/error-305), [`308`](/agents/errors/error-308), [`352`](/agents/errors/error-352), [`420`](/agents/errors/error-420), [`516`](/agents/errors/error-516), [`604`](/agents/errors/error-604), [`605`](/agents/errors/error-605), [`790`](/agents/errors/error-790), [`998`](/agents/errors/error-998). [Troubleshooting by Symptom](/agents/errors/troubleshooting) helps when the code doesn't explain it. The address is predictable: `/agents/errors/error-` followed by the code.

### Other codes

Other codes shown on endpoint pages: `356` invalid credit-card expiry (3D Secure initialize, capture-buyer-token); `600` buyer not found (get-buyer-key); `720` the service was not activated on the account, with the service name in `status_additional_info` (Apple Pay, Google Pay, B2B transfer); `901` invalid JSON (get-transactions); `906` withdrawal not found (credit-match). 

### Codes seen in real integrations (from PayMe support)

| Code | Meaning | What to do |
|------|---------|------------|
| `4` | "Not implemented" (HTTP 500) on `POST /sales`: no payment block, or `sale_type: credit` on a non-card method | Send a payment block; use `credit` only with cards. |
| `109` | Seller not validated or approved | Complete the account verification. |
| `516` | Capture more than 7 days after the authorization | The authorization can no longer be captured; it is not voided by this error. Release it with `refund-sale`, otherwise the card issuer releases it on its own schedule. |
| `518` | "Cannot find authorization transaction": the authorization is no longer open (already captured, voided or failed). A capture with `sale_price: 0` returns `352`, not `518` | Check the sale with `get-sales`. A capture isn't a way to release a hold; use `refund-sale` on the authorized sale. |
| `752` | "Invoice document generation failed": the invoicing provider rejected the document, usually its credentials | Check the invoicing service settings on the account. |
| `20001` | The acquirer declined a forwarded void or refund | Contact PayMe with `payme_sale_id` and the time. |




### Israeli direct debit

When a bank authorization changes, the `sale-il-direct-debit-update` callback carries `authorization_status` and `authorization_error_code`. 

| `authorization_status` | Meaning | Effect |
|------------------------|---------|--------|
| `1` | Success | Authorization active |
| `2` | Failed | Failed |
| `3` | Canceled | Canceled |
| `4` | Unknown | Failed |
| `5` | Moved from previous account | Failed |
| `6` | Account changed | Failed |
| `13` | Frozen authorization reactivated | Authorization active |
| `14` | Sent to the bank | Pending |
| `15` | Sent to the bank again | Pending |
| `16` | Details missing | Failed |
| `17` | Details incorrect | Failed |
| `18` | Already processed (success) | Authorization active |



`authorization_error_code` is passed through unchanged from the bank side. Statuses `14` and `15` keep the authorization pending and normally send no callback.

## Other APIs

Error formats of the other APIs are documented with them: [B2B payment contracts](/b2b-payments/contracts/overview#errors), [Keep](/keep/partners-api/overview#errors-and-rate-limits), [Products & Customers](/products-and-customers/authentication/hosts-authentication-and-errors#errors).

## Related status lists

Not errors, but often needed when handling them: [Sale Statuses](/payments/codes-statuses/sale-statuses), [Transaction Statuses](/payments/codes-statuses/transaction-statuses), [Subscription Statuses](/payments/codes-statuses/subscription-statuses).