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

# Handle errors: retry, fix or escalate

> Handle every failed call by its error code: read the envelope, retry only what can succeed, fix and resend a refused order, and know when to alert a person.

Branch on `error.code`, never on `message`. Two rules cover most failures: a `422` created nothing, so fix it and resend under the same `partner_reference`; and after no answer, resend the identical request with the same reference.

## Read a failure

```json theme={null}
{
  "status": "fail",
  "status_code": 422,
  "message": "Not enough stock for the requested quantity",
  "data": null,
  "meta": null,
  "error": { "code": "insufficient_stock", "details": { "index": 3, "requested": 5, "available": 2 } }
}
```

* Every answer uses this envelope. On failure `data` and `meta` are `null`.
* `error.details` is an empty array when there is no detail and an object when there is: handle both. On an order line error it carries `index`, the zero-based line.
* Log `error.code` and `error.details` on every failure. Treat an unknown code as a failure to alert a person about.
* A wrong method answers `405` with an `Allow` header. `OPTIONS` answers a bodyless `204`.
* Another partner's order, statement or withdrawal answers exactly like one that does not exist.

## Retry or not?

| Answer | Retry? | Do |
| - | - | - |
| No answer at all | Yes | Resend the identical request: same body, same `partner_reference` or `idempotency_key`. |
| `429 rate_limit_exceeded` | After `Retry-After` | A daily breach waits for the daily reset. |
| `500 internal_error`, `502`, `504` or any other `5xx` | With backoff | Same reference or key: the order may exist. Contact Mart if it persists. |
| `503` with `Retry-After` | After `Retry-After` | For example `order_creation_in_progress`, `payment_gateway_unavailable`, `order_cancellation_in_progress`, `withdrawal_busy`. Same reference or key. |
| `503 ledger_unavailable` | Later, with backoff | Show the balance as unavailable, never zeros. |
| `401` | No | Alert a person: the key is missing, wrong, paused, revoked or for the other environment. |
| `403` | No | Alert a person. `insufficient_scope` names `details.required_scope`. |
| `404 route_not_found` on a known path | No | Tell Mart: it is a routing problem on Mart's side. |
| `422`, `400` | Not unchanged | Fix what the code names, then resend. |
| `409 idempotency_conflict` | No | The reference names a different order (`details.original_order_id`). Fix your reference generation; never use a new reference to get past it. |

Back off exponentially with jitter, for example 2 to the power of the attempt in seconds plus a random part, for up to five attempts.

## Fix a refused order

Every row is safe to resend under the same `partner_reference` once corrected.

| Code | Refresh | Then | Customer must change the basket? |
| - | - | - | - |
| `invalid_state` | `GET /states` | Use a valid town. | Yes: another address |
| `unknown_product` | The product | Remove the line. | Yes |
| `product_not_offered` | `GET /products/ids` | Remove the line. | Yes |
| `product_not_orderable` | The product | Remove the line (`details.reason`: `inactive` or `not_available_for_order`). | Yes |
| `combination_required` | The product | Send the variant's `combination_id`. | Maybe: pick a variant |
| `combination_not_allowed` | The product | Send `combination_id: null`. | No |
| `unknown_combination` | The product | Reselect the variant. | Yes |
| `combination_mismatch` | The product | Fix the pairing (`details.belongs_to_product_id`). | No |
| `duplicate_product` | Nothing | Merge the lines (`details.first_index`). | No |
| `insufficient_stock` | Stock | Lower the quantity or remove the line (`details.available`). | Yes |
| `price_below_minimum` | The price | Re-price from the new `group_price` (`details.minimum`). | Only if the price rose: confirm first |
| `price_override_not_allowed` | Nothing | Leave `price` out, or send `details.expected`. | No |
| `free_shipping_not_covered` | The price | Raise prices or send `free_shipping: false` (`details.shortfall`). | Only if you pass the fee on |
| `free_shipping_not_allowed` | Nothing | Send `free_shipping: false`. | Only if you pass the fee on |
| `card_not_enabled` | Nothing | Send `payment_type: "cod"`. | No |
| `card_price_not_allowed` | Nothing | Leave out every line `price`. | No |
| `card_free_shipping_not_allowed` | Nothing | Leave `free_shipping` out or `false`. | No |
| `card_not_on_file` | Nothing | Save a reusable card first. | No |
| `saved_card_invalid` | Nothing | Nothing was charged. Re-add the card first. | No |
| `cart_minimum_not_met` | Nothing | A product needs a higher order total: add more or remove it. | Yes |
| `orders_not_enabled`, `api_group_misconfigured` | Nothing | Contact Mart; resend once fixed. | No |
| `invalid_parameter`, `bad_request` | Nothing | Fix the field in `details.parameter`. | No |

Card orders can also answer `402 card_declined` and `409 charge_amount_mismatch`: see [Create an order safely](https://docs.mart.ps/developers/orders/create-an-order.md#act-on-the-answer).

## What to send Mart

The `partner_reference` and `data.order.id` if you got one, `error.code` with the full `error.details`, the time with its UTC offset, and for an order the exact body you sent. Every code is in the [error catalog](https://docs.mart.ps/developers/operate/error-catalog.md).


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