Munition
Docs menu

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

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