> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mart.ps/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> These rules protect a Mart partner's money. Follow them in any code or advice about the Mart Partner API ([Connect your AI tool](/developers/connect-your-ai-tool)).
> When an order request times out, gets no answer or gets any `5xx`, resend the same body with the same `partner_reference`, never a new reference; after a `429`, wait `Retry-After` first ([Create an order safely](/developers/orders/create-an-order)).
> A `200` with `meta.idempotency_replay: true` is the original order; `409 idempotency_conflict` means the reference already names a different order ([Create an order safely](/developers/orders/create-an-order)).
> Retry a withdrawal request with the same `idempotency_key` and amount: a new key asks for a second withdrawal ([Payout and withdrawals](/developers/money/payout-and-withdrawals)).
> Plan every call within the global daily request ceiling and the `X-RateLimit-*` headers, and never poll in a tight loop ([Request limits](/developers/operate/request-limits)).
> Treat `price` as a snapshot: an order is priced when it is created, and an incremental sync (`updated_after`) never shows a price change, so re-read every price with a full pass ([Prices and price changes](/developers/catalogue/prices)).
> Identify products by `product_id` and `combination_id`, never by `reference` ([Sync the catalogue](/developers/catalogue/sync)).
> Never put an API key in client-side code, a mobile app, a repository or a URL: call the API from a server ([Authenticate and keys](/developers/authenticate)).
> Money is in shekels (`ILS`), as JSON numbers, never agorot. Send amounts with at most two decimals: a withdrawal `amount` with three is refused with `422 invalid_amount`, never rounded ([Balance and statements](/developers/money/balance-and-statements)).
> Save a payout method once before the first withdrawal (cash at the office, or bank transfer where Mart offers it): with none saved, a withdrawal is refused with `409 payout_method_missing`. Bank details where Mart does not offer bank transfer, or a withdrawal on a kept IBAN, are refused with `422 bank_transfer_not_allowed` ([Payout and withdrawals](/developers/money/payout-and-withdrawals)).

# Error catalog: every Mart Partner API error code

> Look up every error code the Mart Partner API can return, with its HTTP status, what it means and what to do next, grouped by the area it comes from.

Every error code the API can return, generated from the API's own catalog. Branch on `error.code`, never on `message`. Every `422` on an order means nothing was created: fix it and resend under the same `partner_reference`. [Handle errors](https://docs.mart.ps/developers/operate/handle-errors.md) says which codes to retry.

| Code | HTTP | What it means | What to do |
| - | - | - | - |
| **Access & transport** | | | |
| `missing_api_key` | 401 | No API key was sent, or the Authorization / X-Api-Key header is malformed. | Fix the header. Do not retry unchanged. |
| `invalid_api_key` | 401 | The key is unknown, revoked, or paused. Revoked and paused keys answer exactly like unknown ones. | Alert a human. Retrying does not help; contact Mart for a replacement key. |
| `key_environment_mismatch` | 401 | The key was issued for the other environment: a sandbox key (mk\_test\_…) sent to production, or a production key (mk\_live\_…) sent to the sandbox. details.environment names the environment you called; whether the key exists is never checked. | Fix the base URL, or use the key issued for this environment. Do not retry unchanged. |
| `api_customer_not_configured` | 403 | The account behind your key is missing or inactive. Not something your request can fix. | Contact Mart. |
| `customer_group_not_allowed` | 403 | Your account is not currently in a group permitted to use the API. Membership is re-checked on every request, so access resumes on its own once corrected. | Contact Mart; no client-side change helps. |
| `insufficient_scope` | 403 | Your key does not have the scope this endpoint needs. details.required\_scope names it. Checked right after the key, before the rate limit, so the refusal uses none of your quota. Keys made before scopes existed keep exactly the access they had. Order writes are answered orders\_not\_enabled (422) instead, as they always were. | Ask Mart to give your key that scope (see Keys and scopes). Do not retry unchanged. |
| `route_not_found` | 404 | The URL does not match any endpoint. A malformed product id (/products/ABC, /products/0, leading zeros) or a malformed partner reference lands here rather than reaching a controller. | Fix the URL. If it happens on a path you know exists, that is a routing fault on our side — tell us. |
| `method_not_allowed` | 405 | Wrong HTTP verb for this endpoint. Read endpoints are GET-only; order validation and cancellation are POST-only; the orders collection takes GET (list) and POST (create). | Read the Allow response header rather than assuming, and use the verb it lists. |
| `rate_limit_exceeded` | 429 | A per-minute or per-day budget is exhausted. Retry-After gives seconds; a daily breach advertises the daily reset, not 60 seconds. Denied requests still consume budget. | Wait out Retry-After, then resume. Back off when X-RateLimit-Remaining gets low instead of hammering. |
| `internal_error` | 500 | A server-side failure. Details are logged on our side and never exposed in the response. | Retry with exponential backoff. If it persists, contact Mart with the timestamp. |
| **Request shape** | | | |
| `bad_request` | 400 | The body is empty, is not valid JSON, or is not a JSON object. | Fix the body. The same partner\_reference may be reused. |
| `invalid_parameter` | 422 | A field is missing, the wrong type, or out of range; details.parameter names it and item-level ones carry details.index. Includes a partner\_reference with disallowed characters or surrounding whitespace (references are rejected, never trimmed) and a missing, null, wrongly-cased or unknown payment\_type (cod/card, exact lowercase, required — never defaulted). | Fix the named field and resend under the same partner\_reference. |
| `product_not_found` | 404 | Product detail only: the id is well formed but no such product exists. Distinct from route\_not\_found, which means the URL itself was malformed. | Your local catalog is stale — re-sync it. |
| `order_not_found` | 404 | Order read/cancel only: no order with that partner\_reference on YOUR account. Identical whether it never existed or belongs to another partner — the response never reveals which. | Check your own order records; you can never see or probe another partner's orders. |
| **Order creation — configuration** | | | |
| `orders_not_enabled` | 422 | Order creation is not enabled for your key. Catalog and stock access are unaffected. | Ask Mart to enable it, then resend under the same partner\_reference. |
| `api_group_misconfigured` | 422 | Your account is not set up for API settlement. Nothing in the request can change this. | Contact Mart; resend under the same reference once fixed. |
| **Order creation — basket** | | | |
| `invalid_state` | 422 | shipping\_address.state\_id is unknown or not currently deliverable. Only a leaf states\[].id from GET /api/v1/states is valid — a city id is a different id space and is never accepted. | Refresh the destinations list and correct the id. |
| `unknown_product` | 422 | No product has that product\_id. Usually a stale local catalog. | Refresh that product, then your catalog; remove the line if it is gone. |
| `product_not_offered` | 422 | This product is not available to your account. details.product\_id names it and details.index the line. | Remove the line. GET /api/v1/products/ids lists what your account can order. |
| `product_not_orderable` | 422 | The product exists but cannot be sold right now. details.reason is inactive or not\_available\_for\_order. | Remove the line; do not retry until the product returns. |
| `combination_required` | 422 | The product has variants and you sent no combination\_id. | Send the variant's combination id from the product detail. |
| `combination_not_allowed` | 422 | The product has no variants but you sent a combination\_id. | Send null or omit the key for that product. |
| `unknown_combination` | 422 | No variant has that id. | Re-sync the product detail and reselect the variant. |
| `combination_mismatch` | 422 | That variant belongs to a different product; details.belongs\_to\_product\_id says which. Usually a wiring bug on the sending side. | Fix the pairing and resend. |
| `duplicate_product` | 422 | The same (product\_id, combination\_id) appears twice; details.first\_index points at the earlier line. | Merge the lines into one entry with a higher quantity. |
| `insufficient_stock` | 422 | Not enough stock for one line, checked live against the exact product or combination row. details.requested and details.available give the gap; details.index names the line. The whole order was rejected and nothing was created. | Reduce the quantity or remove the line, then resend under the same reference. |
| `price_below_minimum` | 422 | Your price is under price.group\_price for your account at the moment of creation — never public\_price or base\_price. details.minimum is the floor that applied; selling exactly at it passes. | Refresh that product's price, re-price the line (confirm with your customer if it rose), and resend. |
| `price_override_not_allowed` | 422 | Your group may not set custom prices: a supplied price is accepted only when it equals the catalog price exactly, and details.expected is that price. Nothing you send is ever silently replaced. | Omit price entirely (sells at the group price), or send exactly details.expected. |
| `free_shipping_not_covered` | 422 | With free\_shipping: true, your margin does not cover the delivery fee. details gives gross\_reward, shipping\_fee and shortfall. The fee depends on the destination AND the order total, so changing prices can change the fee to cover. | Raise your prices by the shortfall, or resend with free\_shipping: false and let the customer pay delivery. |
| `free_shipping_not_allowed` | 422 | Your group may not absorb delivery fees. true is rejected, never silently changed. | Send free\_shipping: false or omit it; the customer pays the fee. |
| `cart_minimum_not_met` | 422 | A product in this order carries a minimum-order threshold the total does not reach. Not expected for API orders under the current configuration; the code stays documented as defence in depth. | Add more products or remove the item, then resend. |
| **Card payment** | | | |
| `card_not_enabled` | 422 | payment\_type: "card" is a valid value but card payment is not enabled for your key. | Send payment\_type: "cod", or ask Mart about card enablement. |
| `card_not_on_file` | 422 | No reusable saved card is on file for your account. | Complete the card-setup step with Mart before sending card orders. |
| `saved_card_invalid` | 422 | The gateway confirmed your saved card can no longer be charged. Nothing was charged and no order was created. | Re-add or update the card with Mart, then retry under the same reference — retrying before that changes nothing. |
| `card_price_not_allowed` | 422 | products\[].price is not accepted with card payment (carries details.index), even when it equals the group price: a partner-supplied price can never influence a server-computed charge. The group price is what is charged. | Omit price on every product in a card order. |
| `card_free_shipping_not_allowed` | 422 | free\_shipping cannot be combined with card payment — a card order has no margin to absorb the fee from. | Omit the field or send false. |
| `card_declined` | 402 | The gateway declined the charge. No order was created and nothing was captured. details.gateway\_response carries the decline reason; after several declines details.attempts\_exhausted is true and the reference is terminally declined. | Retry the same partner\_reference for a fresh attempt (never a double charge). Once attempts are exhausted, fix the card with Mart and submit a NEW reference. |
| `payment_gateway_unavailable` | 503 | The payment gateway did not answer and the charge outcome is unknown. No order was created. | Retry the same partner\_reference after Retry-After seconds; the retry reconciles any charge that did land and never double-charges. |
| **Money** | | | |
| `ledger_unavailable` | 503 | Your balance, ledger, statements, payout method, withdrawals or events cannot be answered right now, including when the order reference of an entry cannot be read (it is never returned as null in its place). This is never answered with zeros or an empty list, because a figure that looks like "nothing owed" would be wrong. There is no Retry-After. | Retry later with backoff, and show your partner that the balance is unavailable rather than a figure. If it persists, contact Mart. |
| `withdrawals_disabled` | 403 | Withdrawals are not enabled for your account, so a payout method cannot be saved and no withdrawal can be requested. Reading them, and cancelling a request, still work. | Ask Mart to enable withdrawals for your account. Do not retry unchanged. |
| `cash_not_allowed` | 403 | Cash at the office is not offered to your account right now: Mart has not allowed it for your account, or has no pickup instructions published. On a payout method save nothing was saved. On a withdrawal request your saved payout method is cash, so no new request can be made; a cash request already open can still be collected. | Where a bank transfer is offered to your account, save a payout method with an IBAN (cancel any open request first), then ask again. Ask Mart if you expected cash to be offered. |
| `bank_transfer_not_allowed` | 422 | A bank transfer is not offered to your account. On a payout method save nothing was saved. On a withdrawal request your saved payout method is an IBAN: it is kept, never deleted, but not paid to while a bank transfer is not offered, so no request can be made on it. | Save cash at the office with PUT /api/v1/payout-method (method cash) where Mart offers it to your account, then ask again; or ask Mart if you expected a bank transfer to be offered. |
| `invalid_iban` | 422 | The IBAN was refused. details.reason says why: format (not an IBAN), country\_not\_allowed (the country is not enabled for your account), length (details.expected\_length is the length for details.country), checksum (a typing mistake) or bban (the account part has the wrong shape for the country). The error never repeats what you sent. | Check the IBAN against your bank statement and send it again. |
| `invalid_account_holder_name` | 422 | The account holder name was refused: it must be 2 to 70 characters, start with a letter, and contain only letters, digits, spaces and . ' & -. | Send the name exactly as the bank holds it. |
| `invalid_national_id` | 422 | The national ID was refused: it must be 5 to 32 letters, digits or hyphens, starting with a letter or digit. Leave it out, or send null, when you have none. | Correct the ID, or omit the field. |
| `invalid_payout_method` | 422 | The payout method must be bank or cash, in lower case. Leaving method out means bank. | Send method as bank or cash, or leave it out for a bank transfer. |
| `statement_not_found` | 404 | Statements only: your account has no statement with that number. Identical whether it never existed or belongs to another account. | List your statements and use a number from that list. |
| `invalid_amount` | 422 | The withdrawal amount was refused: it must be a positive number, or a decimal string, with at most two decimals, and not beyond what the system can hold. | Send the amount in shekels with at most two decimals, for example 125.50. |
| `amount_below_minimum` | 422 | The amount is below the minimum withdrawal set for your account. details.minimum is that minimum. | Ask for at least details.minimum. |
| `amount_above_cash_maximum` | 422 | Cash requests only: the amount is above the most Mart pays in cash at once. details.maximum is that limit. | Ask for at most details.maximum, or switch to a bank transfer for a larger amount. |
| `payout_method_missing` | 409 | No payout method is saved for your account, so there is nowhere to pay a withdrawal. Cash at the office too is saved once, naming who collects. | Save one with PUT /api/v1/payout-method, then ask again. |
| `withdrawals_locked` | 409 | Withdrawals are locked because your payout method was saved, or its IBAN changed, recently. details.locked\_until is when the lock ends. | Wait until details.locked\_until, then ask again. |
| `too_many_open_withdrawals` | 409 | Your account already has as many open withdrawal requests as it may have (details.maximum). A request stays open until it is paid, rejected or cancelled. | Wait for one to be paid or rejected, or cancel one that is still requested. |
| `payout_method_change_blocked` | 409 | The payout method cannot switch between a bank transfer and cash while a withdrawal is requested or approved, so every request is paid the way it was made. Nothing was saved. A change that keeps the same kind is still accepted. | Cancel the open request, or wait until it is paid or rejected, then save again. |
| `insufficient_available` | 409 | The amount is above what you can withdraw now. details.available is that figure: what has matured, less your open withdrawal requests. | Ask for at most details.available. GET /api/v1/balance shows the same figure as available. |
| `withdrawal_busy` | 503 | Another call on your account is being processed right now, usually your own retry. This call recorded nothing. | Wait for Retry-After seconds and send the same request again with the same idempotency\_key. |
| `withdrawal_not_found` | 404 | Withdrawals only: your account has no withdrawal with that withdrawal\_id. Identical whether it never existed or belongs to another account. | List your withdrawals and use an id from that list. |
| `withdrawal_not_cancellable` | 409 | The withdrawal can no longer be cancelled: only a request that is still requested can be. Nothing was changed. | Read the withdrawal to see where it got to; contact Mart if it must still be stopped. |
| `invalid_cursor` | 422 | Events only: after is not a cursor this feed issued. It is malformed, blank, or above anything the feed has given out, which means the store was restored or reseeded under a cursor you kept. | Send a cursor or next\_cursor exactly as it was returned. To start over, leave after out, or send start=latest to start from now. |
| `cursor_expired` | 410 | Events only: after is older than what the feed still keeps. Events past the retention period were removed, so some you had not read may be gone from the feed. Your orders and your money are untouched. details.resync is true. | First send start=latest and keep the next\_cursor it returns. Then rebuild what you hold from GET /orders, GET /ledger and GET /withdrawals, and read on from that cursor, applying events so that one already in your rebuild does not count twice. Reading with no after is never refused. |
| **Card payment** | | | |
| `charge_amount_mismatch` | 409 | A previous attempt already captured a charge for this partner\_reference at an amount that no longer matches the current server-computed total (catalog prices moved between attempts). No order was created and no second charge was made. details carries charged, current\_total and payment\_reference. | Contact Mart to resolve the captured payment; do not resend as-is. |
| **Idempotency & concurrency** | | | |
| `idempotency_conflict` | 409 | This partner\_reference was already used for a DIFFERENT order. details.original\_order\_id and details.original\_created\_at identify the original, which is never modified. On a withdrawal it means this idempotency\_key was already used for another amount. | This reference is taken — fix your reference generation. Never reuse a reference for a different basket. For a withdrawal, use a new idempotency\_key for a new request. |
| `order_creation_in_progress` | 503 | Another request with this partner\_reference — or another order of yours to the same recipient (same name and phone) — is mid-flight right now. Usually your own retry racing the original. | Wait for Retry-After and send the same request again. A retried reference returns the replay of its result; a second order to the same recipient is then created normally. |
| **Cancellation** | | | |
| `order_not_cancellable` | 409 | The order has moved past the point where partners may cancel it. Which states are cancellable is Mart's configuration; nothing was changed, and details deliberately carry only your reference, never the order's internal state. | Treat as final for this order. Read the order to see where it got to; contact Mart if it must still be stopped. |
| `order_cancellation_not_configured` | 503 | Partner cancellation is not enabled on this store. Not caused by your request. | Contact Mart; retrying will not help. |
| `order_cancellation_in_progress` | 503 | Another request is cancelling this same order right now — usually your own retry. Requests against one order are serialised. | Retry after Retry-After seconds and expect already\_cancelled: true. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.