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

> ## Agent Instructions
> Notes on the Listo Partner Delivery API:
> - Every endpoint is under `https://api.listo.delivery/v1/` and authenticates with a bearer API key.
> - This documentation site is at https://docs.listo.delivery. The full machine-readable reference is the OpenAPI document at https://api.listo.delivery/docs/openapi.yaml (served by the API host, not by this site).
> - Any page of this site is also available as raw markdown by appending `.md` to its URL, for example https://docs.listo.delivery/en/guides/webhooks.md. The index of every page is https://docs.listo.delivery/llms.txt and all of them in one file is https://docs.listo.delivery/llms-full.txt.
> - Every page is published in English under https://docs.listo.delivery/en/ and in Spanish under https://docs.listo.delivery/es/, with the same path after the language. The API reference is under https://docs.listo.delivery/api-reference/ in English and https://docs.listo.delivery/es/api-reference/ in Spanish.
> - To debug an integration yourself: `GET /v1/request_logs` lists the calls your keys made with what you sent and what was answered, `GET /v1/events` lists the events Listo emitted, `GET /v1/webhook_deliveries` lists every attempt to deliver them, `POST /v1/events/{id}/resend` sends one event again and `POST /v1/test_webhooks` sends a sample event (`"test": true`). The page https://docs.listo.delivery/en/guides/debugging describes them. A resent event is a snapshot from when it happened; `GET /v1/deliveries` is still how you recover current state.
> - Every error response has `error.doc_url`, a page that explains that error code and what to do, and `error.request_id`, the same value as the `X-Request-Id` response header. All the pages are listed at https://docs.listo.delivery/en/errors. Filter `GET /v1/request_logs` with `request_id` to read the logged call.
> - A `409 account_exists` from `POST /v1/stores` means the restaurant already has its own Listo account: connect it instead of creating it, as the page https://docs.listo.delivery/en/guides/connect-existing-account describes.
> - Every live store carries one Plan Listo, charged to the partner. The exception is a connected restaurant that had already paid its current month: it keeps paying its own plan until its next renewal, shown as `paid_by: "store"` with the handover date in `pending_paid_by_on`. A `402 plan_required` from a quote, a delivery create or a retry means the store's plan is not paid or has ended; the page https://docs.listo.delivery/en/guides/plan-and-billing describes the plan, the `plan` block on a store and how to end or restart it.
> - An AI assistant (Claude Code, Cursor, Codex) can act through the same API key at `https://api.listo.delivery/mcp`, an MCP server over Streamable HTTP authenticated with `Authorization: Bearer <API key>`. Every tool runs the matching `/v1/` endpoint, and each one that moves money first previews and then needs a confirmation token; the page https://docs.listo.delivery/en/guides/connect-ai-client lists the tools and describes the two steps.

# Errors

> Every error code the Listo Partner API returns, what it means and what to do about it.

Every error response has the same shape: an `error` object with a `code`, a human readable `message`, the `param` that failed when there is one, `retryable`, a `doc_url` that links to the page for the code, and the `request_id` of the call. Branch on `code`, never on `message`, which can change wording.

`error.request_id` is Listo's id for the request, the same value as the `X-Request-Id` response header and the `request_id` in your [request logs](https://docs.listo.delivery/en/guides/debugging.md). Quote it when you write to support.

| Code | HTTP status | Retryable | What it means |
| - | - | - | - |
| [`invalid_api_key`](https://docs.listo.delivery/en/errors/invalid_api_key) | `401` | No | The API key on the request is missing, wrong, revoked, or belongs to a different mode than the thing you asked for. |
| [`insufficient_balance`](https://docs.listo.delivery/en/errors/insufficient_balance) | `402` | No | The balance of the account that pays does not cover what this request would spend or move. |
| [`not_found`](https://docs.listo.delivery/en/errors/not_found) | `404` | No | There is no resource with that id for the API key you used. |
| [`quote_expired`](https://docs.listo.delivery/en/errors/quote_expired) | `400` | No | The quote you are creating a delivery from has expired. |
| [`quote_consumed`](https://docs.listo.delivery/en/errors/quote_consumed) | `400` | No | That quote was already used to create a delivery, and a quote can be used once. |
| [`validation_failed`](https://docs.listo.delivery/en/errors/validation_failed) | `422` | No | A field of the request is missing, malformed or out of range. Nothing was created. |
| [`out_of_service_area`](https://docs.listo.delivery/en/errors/out_of_service_area) | `422` | No | The dropoff address is outside the area Listo delivers to from this store. |
| [`address_undeliverable`](https://docs.listo.delivery/en/errors/address_undeliverable) | `422` | No | The dropoff address was rejected as one a courier cannot deliver to. |
| [`address_not_found`](https://docs.listo.delivery/en/errors/address_not_found) | `422` | No | The address you sent as free text could not be located on a map. |
| [`cash_over_cap`](https://docs.listo.delivery/en/errors/cash_over_cap) | `422` | No | The cash the courier would collect at the door is above the cash limit. |
| [`card_below_minimum`](https://docs.listo.delivery/en/errors/card_below_minimum) | `422` | No | The amount the customer owes by card is below the smallest card payment that can be charged. |
| [`card_not_ready`](https://docs.listo.delivery/en/errors/card_not_ready) | `422` | No | The store has no connected account that can accept card payments yet. |
| [`idempotency_conflict`](https://docs.listo.delivery/en/errors/idempotency_conflict) | `409` | No | The idempotency key was already used with a different body, or the first request with that key is still running. |
| [`not_cancellable`](https://docs.listo.delivery/en/errors/not_cancellable) | `409` | No | The delivery or the plan is in a state that no longer allows cancelling. |
| [`not_reschedulable`](https://docs.listo.delivery/en/errors/not_reschedulable) | `409` | No | The delivery was already dispatched, so its pickup window can no longer be moved. |
| [`cancel_failed`](https://docs.listo.delivery/en/errors/cancel_failed) | `409` | Yes | The cancellation did not go through. Nothing changed, and the delivery is exactly as it was. |
| [`rate_limited`](https://docs.listo.delivery/en/errors/rate_limited) | `429` | Yes | You sent too many requests in a short time. This request was not processed. |
| [`provider_unavailable`](https://docs.listo.delivery/en/errors/provider_unavailable) | `503` | Yes | Dispatch is temporarily unavailable. Nothing was created. |
| [`internal_error`](https://docs.listo.delivery/en/errors/internal_error) | `500` | Yes | Something failed on Listo's side. It is not a problem with your request. |
| [`not_retriable`](https://docs.listo.delivery/en/errors/not_retriable) | `409` | No | Only a delivery that was left without a courier can be retried, and this one is not in that state. |
| [`console_access_required`](https://docs.listo.delivery/en/errors/console_access_required) | `422` | No | The store has no console, so there is no owner login to create. |
| [`not_editable`](https://docs.listo.delivery/en/errors/not_editable) | `409` | No | The dropoff instructions can no longer change on this delivery. |
| [`account_exists`](https://docs.listo.delivery/en/errors/account_exists) | `409` | No | That owner email already signs in to a Listo account, so a second store cannot be created for it. |
| [`code_expired`](https://docs.listo.delivery/en/errors/code_expired) | `400` | No | The connection code was exchanged after its 24 hours ran out. |
| [`payout_account_not_ready`](https://docs.listo.delivery/en/errors/payout_account_not_ready) | `422` | No | There is no bank account that can receive this withdrawal. |
| [`not_refundable`](https://docs.listo.delivery/en/errors/not_refundable) | `409` | No | This order has no collected card payment left to give back. |
| [`refund_amount_too_large`](https://docs.listo.delivery/en/errors/refund_amount_too_large) | `422` | No | The refund amount is more than this order has left to refund. |
| [`unsupported_country`](https://docs.listo.delivery/en/errors/unsupported_country) | `422` | No | Listo delivers in Mexico only, and this address is in another country. |
| [`pickup_point_pending`](https://docs.listo.delivery/en/errors/pickup_point_pending) | `409` | Yes | The store's pickup point is not confirmed yet, so no courier can be requested from it. Nothing was created. |
| [`same_day_cap_exceeded`](https://docs.listo.delivery/en/errors/same_day_cap_exceeded) | `422` | No | The account reached the same-day withdrawal limit for today. |
| [`same_day_below_minimum`](https://docs.listo.delivery/en/errors/same_day_below_minimum) | `422` | No | The amount is below the minimum for a same-day withdrawal. |
| [`plan_required`](https://docs.listo.delivery/en/errors/plan_required) | `402` | No | This live store has no paid, active plan, so it cannot request couriers. Nothing was created. |
| [`order_too_large`](https://docs.listo.delivery/en/errors/order_too_large) | `422` | No | The cart is too large for one courier trip. Nothing was priced, created or charged. |
| [`not_reactivatable`](https://docs.listo.delivery/en/errors/not_reactivatable) | `409` | No | The store's plan has not ended, so there is nothing to reactivate. |
| [`plan_ended`](https://docs.listo.delivery/en/errors/plan_ended) | `409` | No | The store's plan cancellation already took effect, so it can no longer be undone. |
| [`charge_in_progress`](https://docs.listo.delivery/en/errors/charge_in_progress) | `409` | Yes | A card charge for the store's plan is still being processed by the bank. Nothing new was charged. |
| [`no_couriers_available`](https://docs.listo.delivery/en/errors/no_couriers_available) | `409` | Yes | Every courier near the trip is busy right now, so no price came back. Nothing was created. |
| [`webhook_endpoint_not_configured`](https://docs.listo.delivery/en/errors/webhook_endpoint_not_configured) | `409` | No | There is no webhook URL set for this mode, so there is nowhere to send the event. |
| [`event_not_resendable`](https://docs.listo.delivery/en/errors/event_not_resendable) | `409` | No | Courier location events are never sent again, because the next position replaces them within seconds. |
| [`resend_limit_reached`](https://docs.listo.delivery/en/errors/resend_limit_reached) | `429` | Yes | This event was already sent again 5 times in the last hour. |
| [`test_webhook_limit_reached`](https://docs.listo.delivery/en/errors/test_webhook_limit_reached) | `429` | Yes | 30 test webhooks were already sent in the last hour for this mode. |
| [`read_only_key`](https://docs.listo.delivery/en/errors/read_only_key) | `403` | No | The API key is read-only, and this request would create, change or cancel something. Reads still work with that key. |


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