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

# Errors

> The Droplinked error envelope, HTTP status usage, and the machine-readable codes a payments integration will actually hit.

## The error envelope

Errors do **not** reuse the success envelope. They carry an extra `status` field and nest
the message one level deeper:

```json Success theme={null}
{ "statusCode": 200, "message": null, "data": { "...": "..." } }
```

```json Error theme={null}
{ "statusCode": 401, "status": "failed", "data": { "message": "Unauthorized" } }
```

Read the message from `data.message`. Read the status from the HTTP status line — the
`statusCode` field mirrors it and is there for clients that lose the status line through a
proxy.

> [!WARNING]
>
> One exception worth knowing before you write a parser: a request that never reaches a
> mounted route is answered by the framework's not-found handler, which returns
> `{"statusCode":404,"status":"failed","data":{"message":"Cannot GET /the/path"}}`. If you
> see that `Cannot <METHOD> <path>` string, the route does not exist on that host — it is not
> an auth or permission failure. A route that exists but rejects you returns `401`, not `404`,
> except where noted below.

## HTTP status usage

| Status | Meaning |
| - | - |
| `200` | Success. Payload in `data`. |
| `400` | Request rejected — validation, or a state machine that will not accept the transition. |
| `401` | Missing or invalid credential. |
| `402` | Payment required — the x402 challenge. The body is the payment descriptor, not an error. See [Agentic payments (x402)](/agentic/x402-payments.md). |
| `403` | Authenticated, but not permitted (for example a customer token attempting a merchant-only action). |
| `404` | Not found — **also** returned for a resource that exists but belongs to another tenant. Cross-tenant reads are deliberately indistinguishable from "does not exist". |
| `429` | Throttled. See [Rate limits](/api-reference/rate-limits.md). |
| `503` | A dependency is disabled or unreachable (feature flag off, facilitator down). |

## Codes you will hit

These are stable, machine-readable strings. Match on the code, never on the message text.

### Checkout and PSP readiness

Returned by `GET /checkout/:shopUrl/payment-intent-resolver`, inside
`data.meta.breakerSkipped[]`, to explain why a payment method the shop nominally has is not
being offered:

| Code | `detail` | Meaning |
| - | - | - |
| `PSP_ACCOUNT_NOT_READY` | `STRIPE_CHARGES_DISABLED` | The merchant's connected account exists but Stripe has not enabled charges on it. Do not render the card slot. |

A live response for a shop in that state:

```json theme={null}
{
  "statusCode": 200,
  "message": null,
  "data": {
    "card": { "provider": null, "label": "", "accountId": null, "renderer": null, "publishableKey": null },
    "paypal": null,
    "crypto": null,
    "x402": null,
    "wallet": [],
    "currency": { "abbreviation": "USD", "symbol": "$", "conversionRateToUSD": 1 },
    "meta": {
      "resolvedAt": "2026-09-20T23:29:59.092Z",
      "source": "shopPaymentMethodsV2",
      "shopId": "<shop id>",
      "breakerSkipped": [
        { "provider": "STRIPE", "reason": "PSP_ACCOUNT_NOT_READY", "detail": "STRIPE_CHARGES_DISABLED" }
      ]
    }
  }
}
```

Resolve payment availability at request time from this endpoint. A shop's configured
method list is **not** the same thing as a method that can take money right now.

### x402 settlement

| Code | Status | Meaning |
| - | - | - |
| `X402_NOT_CONFIGURED` | `503` | x402 is enabled but no facilitator URL is configured on this environment. |
| `X402_FACILITATOR_UNAVAILABLE` | `503` | The facilitator is configured but unreachable, or its circuit breaker is open. |
| `X402_ORDER_NOT_CONFIRMABLE` | `400` | The order is not in a payable state. |
| `X402_SETTLE_FAILED` | `400` | The facilitator rejected the settlement; the reason is appended to the message. |
| `MERCHANT_PAYOUT_WALLET_UNSET` | — | Emitted when a settlement would have no merchant destination. Counted, not raised to the caller. |

### Agent surfaces

| Code | Meaning |
| - | - |
| `AGENT_CHECKOUT_MANIFEST_DISABLED` | The agent checkout manifest is not enabled on this environment. The MCP tool returns this as an `isError` result, not an HTTP failure. |

### Throttling

```json theme={null}
{ "statusCode": 429, "status": "failed", "data": { "message": "ThrottlerException: Too Many Requests" } }
```

## What to do with an unknown code

Codes are added as subsystems learn to explain themselves. Treat an unrecognised
`reason`/`code` as a hard failure for that path — do not fall through to a different
payment method on your side. If a code you are seeing is not listed here, tell us: an
uncatalogued code is a documentation bug.


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