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

# Errors and retries

> Four error kinds, their reasons, and idempotent execute

Every execution failure has one of four `errorCode` values, and each one says what to do next. The specific cause is in `details.reason`.

```json theme={null}
{
  "error": "Your payout changed. Please review the new quote.",
  "code": 409,
  "errorCode": "requote",
  "suggestion": "Create a new quote with POST /execution/v3/sell/quotes",
  "details": { "reason": "quote_total_mismatch", "runId": "2267c318-e8ac-40b4-b522-ae216141d95b" },
  "requestId": "58506219-5893-43d4-9948-324c3c0ce362"
}
```

Branch on `errorCode`. Show `error` to the seller. Send `requestId` to support.

## Kinds

| `errorCode` | Status | What to do |
| - | - | - |
| `requote` | **409** | Create a new quote |
| `account_action_required` | **403** | Fix the account, then create a new quote |
| `try_again` | **503** | Retry the same request with backoff |
| `invalid_request` | **400** | Fix the request |

`try_again` includes `details.retryAfterSeconds` when selling is closed. `invalid_request` for one item includes `details.itemIndex`.

## Reasons

**`requote`**: `checkout_expired`, `checkout_not_found`, `checkout_empty`, `listing_unavailable`, `subtotal_mismatch`, `quote_total_mismatch`, `optional_fee_mismatch`, `optional_not_eligible`, `instant_payout_insufficient_credit`, `promotion_code_invalid`, `promotion_code_expired`, `promotion_code_not_eligible`, `promotion_code_exhausted`, `referral_grant_consumed`

**`account_action_required`**: `organization_not_found`, `selling_disabled`, `vacation_mode`, `account_not_approved`, `jurisdiction_blocked`, `address_required`, `payout_method_not_ready`, `sell_limit_exceeded`

**`try_again`**: `selling_closed`, `system_error`

**`invalid_request`**: `invalid_input`, `offer_unavailable`, `own_offer`, `offer_quantity_exceeded`, `no_offers_for_item`

New reasons can be added, so handle an unknown `reason` by its kind. An unknown, expired, or already-failed quote returns **409** `requote` with no `reason`.

## Other errors

| `errorCode` | Status | Meaning |
| - | - | - |
| `validation_error` | **400** | The body, path, or a header failed validation |
| `request_in_progress` | **409** | The same execute is still running; retry after `retry-after` seconds |
| `idempotency_unavailable` | **503** | Retry with backoff |

## Idempotent execute

Execute is idempotent. Its key is the `Idempotency-Key` header, or the `quoteId` when the header is absent.

* A repeat with the same key within **24 hours** returns the first response, with the header `idempotent-replayed: true`.
* A repeat while the first is running returns **409** `request_in_progress`.
* A **5xx** response is not stored, so a retry runs again. After `try_again`, retry the same execute; the quote stays valid until `expiresAt`.
* Keys are 1 to 255 characters, scoped to your organization and to the quote.

A quote places at most one order. Executing it again, even with a new `Idempotency-Key`, returns that order.

On a network error or timeout, retry execute with the same key. You get the order or the error from the first attempt.

Quote is not idempotent. Each call creates a new quote.


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