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