# Errors

## Error response shape (Payments API)

```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, 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](/payments/getting-started/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](/marketplaces-and-platforms/lists-statuses/sale-statuses), [Transaction Statuses](/marketplaces-and-platforms/lists-statuses/transaction-statuses), [Subscription Statuses](/marketplaces-and-platforms/lists-statuses/subscription-statuses).