Errors

Error response shape (Payments API)

{
  "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, and a 500 usually means your request needs fixing, not that PayMe is down.

Getting messages in English

If you omit language, messages come back in Hebrew. Send "language": "en" on every call. Accepted values are he, en, es, ru and ar; any other value returns error 51.

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

⚠ TO CONFIRM: language is honoured on the Payments, subscription, transaction and seller-management endpoints that were checked; please confirm it applies to every Payments endpoint. [Q16]

Common error codes

The tables below cover the codes integrators meet most often.

⚠ TO CONFIRM: Is there an authoritative, complete list of status_error_code values with English meanings that can be published here? [Q14]

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` 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.	Fix the fields listed in `status_additional_info`.
`51`	Unsupported `language` value	Use `he`, `en`, `es`, `ru` or `ar`.
`163`	The seller exists but is inactive	Contact PayMe.
`200`	Merchant was not found: the `payme_client_key` (or `PayMe-Partner-Key`) matches no partner. `status_additional_info` is `payme_client_key`.	Check 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.
`352`	`sale_price` is not numeric or is outside the allowed range	Send minor units within the allowed range.
`353`	`product_name` is missing	Add `product_name`.
`357`	Unknown `sale_type` value	Use a documented `sale_type`.

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.
`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` / the message.	Wait (`Retry-After` header) and check the sale before retrying.

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

The sandbox test cards that produce each one are on Environments.

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).

Products & Customers API

Errors carry status_code 1, a message, and a status_error_code equal to the HTTP status: 400 "Bad Request", 401 "Unauthorized request", 500 "Internal Server Error".

Keep API

OAuth token errors (HTTP 401) return error and error_description.
Some partner endpoints return {"statusCode": 1, "payload": {"message": "..."}}, for example HTTP 429 "Rate limit exceeded" and "Update conflict".
The document-failure webhook example uses errorCode TAX_AUTHORITY_REJECTED ("Document rejected by tax authority - invalid VAT number").

B2B payment contracts (`error_code` on a contract)

`error_code`	`error_text`
`11000`	Recipient Rejected
`11001`	Initiator Canceled
`11002`	Recipient Confirmation Timeout
`11003`	Initiator Confirmation Timeout
`11004`	Payment Processing Failure

This is the complete list. For 11004, error_note is free text and may contain a regular PayMe error message.

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.

⚠ TO CONFIRM: What values can authorization_error_code take (for example "11") and what does each mean? [Q51]

Related status lists

Not errors, but often needed when handling them: Sale Statuses, Transaction Statuses, Subscription Statuses.