# Errors and refunds

What each status code from Munition's paid routes means, what an agent should do next, and what happens when payment settles but the service fails.

Munition checks a request before it settles a payment, so most errors cost nothing. Once a payment has settled, it stays settled: if the service fails after that point, the API says so and keeps the payment. There are no automatic refunds. This page lists the errors, the safe way to retry, and what each service does after settlement.

## Error bodies

Errors are JSON. Most have this shape, where `message` repeats the code and `details` gives the reason:

```json
{ "error": { "code": "invalid_input", "message": "invalid_input", "details": { "issues": [{ "code": "invalid_type", "expected": "string", "received": "undefined", "path": ["q"], "message": "Required" }] } } }
```

That is the answer of `POST /v1/serper/search` to the body `{"gl":"us"}`, which has no `q`, sent with a payment header: the body is checked before the payment is verified, so nothing is charged. Without a payment header, the route answers `402` before it reads the body. Some errors that happen after a payment settled carry the paid call's id instead, so the payment can be traced:

```json
{ "error": { "code": "upstream_failed", "message": "serper responded 500", "provider": "serper", "paidCallId": "pay_V1StGXR8_Z5j" } }
```

Keep `paidCallId` whenever you see it: it identifies the payment.

Two cases differ. A `402` from an x402 route carries its reason in the `PAYMENT-REQUIRED` header (the decoded `error` field); its body is a short `payment_required` error on most routes, and `{}` on HTML to PDF, on Forms and whenever a payment header was refused. The `400` of `POST /v1/render/pdf` has `reason`, up to three `issues` (`path` and `rule`) and a minimal valid `example`, and never echoes your HTML.

## Status codes

| Status | Code | When | What to do |
| --- | --- | --- | --- |
| 400 | `invalid_input` | The body is not JSON or does not match the route's schema, or a flight offer id is empty or longer than 256 characters; `details.issues` lists the problems. Also a renewal of an HTML to PDF file. | Fix the request. Nothing was charged: every route checks its input before settling. A flight search is checked against today's date only when it is new: the same search sent again with the same `Idempotency-Key` after its departure date passed gets its stored result, or `502 upstream_failed` with `paidCallId` if it never finished, never a `400`. |
| 400 | `form_invalid`, `form_forbidden_content` | Forms only: the form definition is invalid, or it asks for passwords, codes or bank details. | Fix the form. Nothing was charged. |
| 401 | `auth_invalid` | A Bearer route without a valid token: a form's answers or close route without its `readToken`, or an account route without a valid account token. | Send the right `Authorization: Bearer` header. |
| 402 | `payment_required` | x402: the request has no payment, and the `PAYMENT-REQUIRED` header says what to pay. MPP routes answer an unpaid request with `402`, a `WWW-Authenticate: Payment` challenge and an `application/problem+json` body (`type`, `title`, `detail`, `challengeId`, `payment`) that has no `error` code. | Pay as in [Pay per call with x402](/docs/payments/x402) and send the request again. |
| 402 | — | x402: the payment header was refused before settlement, for example no matching `accepts` entry, an invalid signature, an expired authorization or too little USDC. The reason is the `error` field of the decoded `PAYMENT-REQUIRED` header. | Sign a new payment against the requirements in that header. Nothing was charged. |
| 402 | `payment_failed` | x402: the payment was verified but the facilitator did not settle it. The `PAYMENT-RESPONSE` header has `success: false` and the reason (the body is `{}` on HTML to PDF and Forms). | The service did not run. Check your wallet's USDC balance and history before paying again, then send the request with a new key. |
| 402 | `invalid_payment`, `payment_expired`, `price_mismatch` | MPP: the `Authorization: Payment` credential was refused; `details.reason` says why, for example `mpp_challenge_expired` (a challenge is valid 5 minutes), `mpp_challenge_not_issued` (the challenge was not issued by Munition or was changed, such as a longer expiry or validity window: its `id` binds every field), `mpp_unsupported_network` (a network other than Base, Polygon or Arbitrum One, such as a testnet), `mpp_amount_mismatch`, `mpp_authorization_already_used`, or `mpp_native_settlement_failed` when submitting the transfer failed. A transfer counts only once it is mined with the expected USDC transfer to Munition: `mpp_settlement_reverted` when it reverted on chain (the authorization was cancelled or the balance was too low) and `mpp_settlement_transfer_missing` when the transaction moved no such USDC; `details.txHash` names it. In both cases nothing was charged and the service did not run. | Request a new challenge with an unpaid call and sign it; after `mpp_settlement_reverted` or `mpp_settlement_transfer_missing`, send it with a new `Idempotency-Key`. After `mpp_native_settlement_failed` the transfer may still have landed: check your wallet's history before paying again. |
| 402 | `insufficient_funds` | Account routes and MCP tools: the account balance is too low. `details.topupUrl` is a top-up link. | Ask the user to add funds, then call again. |
| 403 | `auth_invalid`, `invalid_payment` | Renew or delete an upload with a payment from another wallet than the one that paid for it. Checked before settlement. | Pay from the wallet that paid for the upload. |
| 404 | `invalid_input` | Renew or delete: the upload does not exist or is already deleted (`details.reason`). Checked before settlement. | Check the upload `id`. |
| 404 | `offer_not_found` | Flight offer details: Duffel does not have the offer (an unknown id, or an offer it no longer serves, such as an expired one). Only Duffel knows, so this is found after the payment settled: the payment is kept, and the body has `provider` and `paidCallId`. | Run a new flight search and use a fresh offer id. The same key looks the offer up again without a second charge. |
| 404 | `form_not_found` | The form does not exist, the `readToken` is not this form's, or its answers are past `responsesReadableUntil`. | Check the form id and token. |
| 404 | `forms_disabled` | Every forms route, while the forms service is disabled on the server. | Do not retry: forms are not available. |
| 409 | `idempotency_conflict` | The `Idempotency-Key` was already used for another request (checked before any payment), or for a paid call that did not finish (`details.priorStatus`, such as `failed` or `effect_pending`, sometimes with `paidCallId` and `reason: requires_reconciliation`), or an MPP retry with another credential than the one a call whose payment has not settled was started with (`reason: credential_mismatch`, with `priorStatus` and `paidCallId`; this credential is not settled). Also a renewal past the 30-day limit (`details.reason`), refused before settlement; a paid renewal that the limit stops later carries `paidCallId` (see the rare cases below). | Do not pay again under a new key to recover a paid call: see the table below. For a new request, use a new key. |
| 422 | `upstream_failed` | Web research: the provider rejected the request after the payment settled. The payment is kept and the call stays open; the body has `provider` and `paidCallId`. | The same request with the same `Idempotency-Key` runs again without a second charge, but the provider is likely to reject it again. To send a changed request, use a new key: a new call is a new payment. |
| 426 | `mcp_version_unsupported` | A request with an `x-munitionx402-mcp-version` header older than the minimum the API accepts (`@munition/mcp` sends it). | Update `@munition/mcp`. |
| 500 | `internal` | An unexpected error. On some routes it can happen after settlement: see the table below. | Do not pay again blindly. Retry as the table says, or contact support. |
| 502 | `upstream_failed` | Web research and the flight routes: the provider failed after the payment settled (provider error, rate limit, timeout, an answer that cannot be read). The payment is kept; the body has `provider` and `paidCallId`. | Send the same request again with the same `Idempotency-Key`: it runs again without a second charge. |
| 503 | `render_unavailable` | HTML to PDF: the renderer is not configured on the server. Checked before payment. | Try again later. Nothing was charged. |
| 503 | `render_effect_pending`, `render_settlement_unknown` | HTML to PDF: the payment settled but the PDF was not produced, or the settlement outcome is unknown. The body has `paidCallId`. | Do not pay again. Contact support with `paidCallId`. |
| 503 | `form_effect_pending`, `form_settlement_unknown` | Forms: the payment settled but the form did not open, or the settlement outcome is unknown. The body has `paidCallId`. | Do not pay again. Retry as the table below says, or contact support. |
| 503 | `upload_effect_pending` | Upload slot, renewal or deletion: the payment settled but the API failed before finishing. The body has `paidCallId`; no receipt header is sent, and the answer of the retry that finishes the call can have none either, so keep `paidCallId`. | Do not pay again. Send the same request with the same `Idempotency-Key`, as the table below says: it finishes without a second charge. |
| 503 | `invalid_payment` | MPP: the settlement of this credential is in progress or its outcome is unknown; `details.reason` is `mpp_settlement_in_progress`, `mpp_settlement_concurrent_recovery`, or starts with `mpp_settlement_ambiguous`. With `mpp_settlement_in_progress` and `details.txHash`, the transfer was submitted but not mined within 10 seconds: the service did not run yet, and the call keeps its `paidCallId`. | Wait a few seconds and send the same request with the same credential and `Idempotency-Key`. If the reason starts with `mpp_settlement_ambiguous`, contact support. |

## Retries and Idempotency-Key

Send an `Idempotency-Key` header with every paid request: a new unique value for each new request, and the same value when you send that request again. Munition records each paid call under its route and key; without a key, the payment header itself is the key, and a new signature makes a new call.

- **The first call finished:** the same key returns the stored result, and no second payment is settled. On most x402 routes the payment header is verified before the stored result is looked up, and a payment that has already settled can be refused at that step: sign a new payment for the retry. It is verified, not settled. HTML to PDF and Forms look up the key first, and return the stored result only to the identical request: the same payment header, key and body.
- **The same key for a different request:** every paid x402 and MPP route answers `409 idempotency_conflict` with `details.reason` `Idempotency-Key reused for a different request`, before it reads the payment: nothing is verified or settled. A request is its method, its path and its JSON body; the order of the body's keys and its whitespace do not matter. A key names one request on all routes, so the same key on another route, for another flight offer or for another upload is a different request. Without an `Idempotency-Key`, the payment header or credential is the key. A request refused before its payment was taken, for example with `400 invalid_input` or a refused payment, leaves its key free for another request. Once a request's payment is taken, its key stays with that request, whatever the answer, for 30 days, and for as long as its paid call can still be resumed. After that, the key is no longer refused with `409`: the route then answers with what it stored for the first call, so use a new key for every new request.
- **The first call failed or stopped after settlement:** the same key answers `409 idempotency_conflict`, unless the route resumes the call: see the table below. A new key starts a new paid call.
- **MPP routes:** retry with the same `Authorization: Payment` credential and the same key. A credential is accepted for the 5 minutes its challenge lives; after that most MPP routes answer `402 payment_expired`. To fetch a finished call's result later, sign a new challenge and send it with the same key: the stored result comes back and the new credential is not settled. A call whose payment has not settled yet resumes only with the credential it was started with, so that one key is never charged twice: every MPP route answers another credential `409 idempotency_conflict` with `reason: credential_mismatch`, `priorStatus` and `paidCallId`, before any settlement. Nothing is charged for that credential, and the call can still finish with the one it was started with. Forms is the exception: it wants the original credential, and accepts it after its challenge expired.
- **MCP tools:** every tool call sends a new key, so calling a paid tool again is a new payment. The exception is a web research or flight tool call that failed after its payment: the same tool with the same arguments resumes it (see [Account balance](#account-balance-current)).

## When payment settles but the service fails

What each route does when something fails after its payment settled, as implemented today:

| Service | Routes | After settlement, if the service fails | Retry with the same Idempotency-Key |
| --- | --- | --- | --- |
| Web research, x402 | `POST /v1/exa/*`, `POST /v1/firecrawl/*`, `POST /v1/serper/*` | The payment is kept and the call stays open. `422 upstream_failed` when the provider rejected the request (a 4xx other than 401, 402 and 429), `502 upstream_failed` otherwise (provider error, 429, a provider refusing or missing Munition's own key or account, timeout, an answer that cannot be read). The body has `provider` and `paidCallId`, and the `PAYMENT-RESPONSE` header has the settlement receipt. | Resumes: send the request again with the same key and a newly signed payment, which is verified but not settled. The provider is called again without a second charge; the answer has no new receipt. After a `422`, the provider is likely to reject the same request again. |
| Web research, MPP | `POST /v1/mpp/exa/*`, `POST /v1/mpp/firecrawl/*`, `POST /v1/mpp/serper/*` | The same as x402, with the receipt in the `Payment-Receipt` header. | Resumes: with the same key and any unexpired credential, the provider is called again without a second charge. |
| HTML to PDF | `POST /v1/render/pdf` | The payment is kept. `503 render_effect_pending` with `paidCallId` ("Payment settled; artifact requires manual reconciliation. Do not pay again."). This includes a document that renders to more than 20 pages or 10 MiB, or that exceeds the render time budget. If the settlement outcome itself is unknown: `503 render_settlement_unknown`. | `409 idempotency_conflict` with `reason: requires_reconciliation`. The render is not retried. |
| Upload slot | `POST /v1/uploads`, `POST /v1/mpp/uploads` | The upload URL is created before settlement; only database updates run after it. If they fail, `503 upload_effect_pending` with `paidCallId`, without the receipt header (`PAYMENT-RESPONSE` or `Payment-Receipt`). You pay for the slot: if the file is not uploaded before `uploadUrlExpiresAt` (10 minutes), the payment is not returned. | Resumes: with the same key and the same body (on x402, a payment header that verifies, and it is not settled; on MPP, an unexpired credential), the paid slot (same `id` and `publicUrl`, still owned by the wallet that paid for it) comes back with a new `uploadUrl` and that URL's `uploadUrlExpiresAt` (10 minutes later), without a second charge. After a success, the same slot, with the same `uploadUrl` and its original expiry. |
| Upload renewal | `POST /v1/uploads/{id}/renew`, `POST /v1/mpp/uploads/{id}/renew` | `503 upload_effect_pending` with `paidCallId`, without the receipt header (`PAYMENT-RESPONSE` or `Payment-Receipt`). The renewal is recorded with the payment in one step: it is either applied and stored, or not applied at all. | Resumes: with the same key and a payment from the wallet that paid for the upload (on x402, a payment header that verifies, and it is not settled; on MPP, an unexpired credential), the paid renewal is applied once, without a second charge. A renewal that was already applied is returned as it was, never applied twice. |
| Upload deletion | `DELETE /v1/uploads/{id}`, `DELETE /v1/mpp/uploads/{id}` | The stored file is deleted after settlement; if that fails, `503 upload_effect_pending` with `paidCallId`, without the receipt header (`PAYMENT-RESPONSE` or `Payment-Receipt`): it is only sent with a deletion that succeeds, never with an error. | Resumes: with the same key and a payment from the wallet that owns the upload (on x402, a payment header that verifies, and it is not settled; on MPP, an unexpired credential), the deletion runs again without a second charge. |
| Flight search, x402 | `POST /v1/flights/search` | The payment is kept and the call stays open: `502 upstream_failed` with `provider: duffel` and `paidCallId`, and the `PAYMENT-RESPONSE` receipt. This includes an answer from Duffel that Munition cannot read. | Resumes: send the request again with the same key and a newly signed payment, which is verified but not settled. The search runs again without a second charge; the answer has no new receipt. |
| Flight search, MPP | `POST /v1/mpp/flights/search` | The same as x402, with the receipt in the `Payment-Receipt` header. | Resumes: with the same key and any unexpired credential, the search runs again without a second charge. |
| Airport search | `POST /v1/airports/search` | The same as flight search on x402. | Resumes, as flight search on x402. |
| Flight offer details | `GET /v1/flights/offers/{id}` | The same as flight search on x402, except that an offer Duffel does not have (an unknown id, or an offer it no longer serves, such as an expired one) gives `404 offer_not_found` with the same fields. The offer id itself is checked before any payment step. | Resumes, as flight search on x402. An offer that Duffel does not have fails again. |
| Forms, x402 | `POST /v1/forms` | The payment is kept. `503 form_effect_pending` with `paidCallId`, and in the first response the form's `formId`, `publicUrl` and `readToken`. If the settlement outcome is unknown: `503 form_settlement_unknown`. | With the identical payment header, key and body, the form opens without a second charge. After `form_settlement_unknown`: `409 idempotency_conflict`. |
| Forms, MPP | `POST /v1/mpp/forms` | The same codes. A settlement transaction that failed to submit counts as an unknown outcome, because it may still land on chain. | With the identical credential, key and body, the form opens without a second charge. After `form_settlement_unknown`, the same retry, while the challenge is valid, checks the chain and can finish the call. |

Free routes, such as flight booking links and reading a form's answers, take no payment.

Rare cases, when the API itself fails at the wrong moment:

- If its database fails just after a settlement, the call can stay recorded as `settling`. An x402 retry with the same key then gets `409 idempotency_conflict` with `priorStatus: settling` (with `paidCallId` on the upload and web research routes; on Forms, after a first `503 form_effect_pending`, with `reason: requires_reconciliation`). On MPP routes the first answer is `503 invalid_payment` with `mpp_settlement_in_progress` and `paidCallId`, and the call is kept; the same holds when the transfer is not mined within 10 seconds (with `details.txHash`). 25 seconds later, the same request with the same credential and key finds the transfer on chain and finishes the call without a second charge, or, if the transfer never landed, submits the same authorization again: one authorization, one charge at most (another credential is refused with `409 idempotency_conflict` and `credential_mismatch`).
- If another renewal of the same upload uses up the 30-day limit after a renewal was paid but before it was applied (two renewals at once, or a retry after a `503 upload_effect_pending`), that renewal answers `409 idempotency_conflict` with `paidCallId`, `details.reason` and `details.maxExpiresAt`, and is not applied.
- If the facilitator's answer to a settlement cannot be read, the x402 routes other than HTML to PDF and Forms answer `500 internal` and the call stays `settling`, its outcome unknown.
- For an x402 call left `settling` by either case and paid on Base, Polygon or Arbitrum One, Munition checks the chain every 5 minutes once the call is 10 minutes old. If the transfer landed, the call is open again: the same request with the same key and a newly signed payment (verified, not settled) finishes it without a second charge, except on HTML to PDF, which still needs support. If the authorization was cancelled or expired unused, nothing was charged: the call is marked failed, the same key then gets `409` with `priorStatus: failed`, and a new key starts a new paid call. A payment on Solana still needs support.

In these cases, do not pay again. Unless a retry finishes the call as described above, contact support.

## Refunds

Munition's API has no refund or credit mechanism: no route, tool or background job returns a payment. When a call failed after its payment settled:

1. Do not pay again to recover it, and do not start a new paid call under a new key.
2. Keep the `paidCallId`, the network, the payment header or credential you sent, and the receipt or transaction hash if you have one.
3. Write to **hello@munition.io** with them.

Any resolution is manual: there is no automatic refund and no promised delay.

For HTML to PDF, Munition publishes an owner-approved manual policy, in [skill.md](/skill.md) and in the API's discovery documents. It starts from the actual outcome on chain, since an ambiguous settlement is not proof of payment. Then, in its own words:

> For verified payment and non-delivery, Munition manually delivers the artifact without another charge or issues an explicitly authorized refund after verification. No automatic refund and no promised resolution SLA.

## Account balance (current)

The MCP tools and account routes of the [account balance](/docs/payments#account-balance-current) keep a settled payment the same way when the service fails after it, and return the error with `paidCallId`. Web research and the flight tools answer as their x402 routes: `502 upstream_failed` (`422` when a web research provider rejected the request), or `404 offer_not_found` for a flight offer Duffel does not have, and the call stays open, so the same `Idempotency-Key` resumes it without a second charge. HTML to PDF and Forms answer `render_effect_pending` and `form_effect_pending`, as on their x402 routes. Both MCP adapters (the remote connector and `@munition/mcp`) add a note that says the call was paid, its `paidCallId`, and how to retry it.

Every MCP tool call is a new payment (see above), except a retry of web research or a flight tool that failed after its payment: calling the same tool with the same arguments within 24 hours resumes that paid call without a second charge, on the remote connector and with `@munition/mcp` (the API recognises its calls by their `x-munitionx402-mcp-version` header). Once that call has delivered its result, the same arguments are a new payment again. A low balance returns `insufficient_funds` with a top-up link. On the remote connector, a call over the connection's spend caps is refused before any payment, with `spend_cap_per_call` or `spend_cap_daily`.
