BCK.ROUTER.0001 | 400 | validation | ❌ | Invalid Router payment request | Bad input to the Router: unsupported protocol, a malformed/empty target (no accepts), no fundable option for the funded networks/assets, an upstream pay-to outside the delegation’s allowed recipients, a non-crypto (non-erc4337) delegation, or a missing delegationId. On a slug-routed call, a path that still holds a template placeholder ({jobId}, :id) rather than a real value. And on a catalog service whose results only the paying wallet can read (an endpoint listed with auth: siwx): a paid call funded by an organization wallet, a subscription or a card, which could not read the result back; or wallet-authenticated follow-ups being disabled on this deployment. An MPP evm charge (method="evm") from a wallet that signs through an EIP-7702 smart account (one whose walletMode is eip7702: every personal wallet wherever EIP-7702 is enabled, since the Router migrates it before paying, and an organization wallet in that mode), because the merchant recovers the signer by ecrecover. When the service also offers x402, an unpinned mode-B call or quote is usually moved to that offer by the Router, so this refusal mostly reaches /router/payments (mode A pays exactly the target you pass) and calls pinned to mpp. Pay the x402 offer instead: protocol: "x402" with its accepts on /router/payments, or requireProtocol: "x402" or unset on /router/route and /router/quote (X-Router-Require-Protocol on /router/proxy · /router/svc). A service with no x402 offer cannot be paid from that wallet: use another service. Every cause above is refused before anything is charged. Buyer identity consent also requires a plain API key, a delegation owned by the caller, an HTTPS slug target and an opted-in listing; the streaming consent header must be exactly true or false. The per-failure details names the specific problem. |
BCK.ROUTER.0002 | 409 | business | ❌ | requestId already used | This requestId already minted a credential — that is idempotency working, not an error to route around. If this is a RETRY of the same purchase, reuse the same requestId and take the original paymentId from params. Use a fresh id only for a genuinely DIFFERENT purchase: it mints a second credential and is charged the routing fee again. |
BCK.ROUTER.0003 | 402 | business | ❌ | Delegation budget exceeded, expired, or inactive | The spend would exceed the delegation cap, or the delegation is expired / exhausted / revoked. Report to the human, who can deliberately create a new delegation via POST /api/v1/delegation/create. If the delegation is held by an app connected over OAuth, they disconnect the app in Nevermined and reconnect it with a new cap instead. |
BCK.ROUTER.0004 | 404 | business | ❌ | Router payment not found | No Router payment with that id belongs to the authenticated user. |
BCK.ROUTER.0005 | 409 | business | ❌ | Router payment is not in a settleable state | Only an Issued payment can be marked Settled. Re-reporting the same txHash on an already-Settled payment is a no-op; a different txHash, or a non-Issued state, is rejected. |
BCK.ROUTER.0006 | 500 | integration | ✅ | Error getting router payments summary | Transient server-side error building the payments summary; safe to retry. Inputs are validated upstream (invalid from/to return 400 BCK.ROUTER.0001, granularity is normalized), so this is not a bad-request issue. |
BCK.ROUTER.0007 | 429 | business | ✅ | Too many concurrent routed requests | You have too many in-flight mode-B routed requests (/route, /proxy) open at once. Note a /proxy request keeps its slot for a moment AFTER you receive the response, while its routing fee settles, so you can reach this limit even calling one at a time in a tight loop. Slow the request rate, or let the previous calls settle before starting more. |
BCK.ROUTER.0008 | 403 | business | ❌ | Router requires an EIP-7702 (v2) API key | This is a legacy (v1) API key bound to the old smart account, which cannot sign EIP-3009 from the unified funded wallet. Create a new API key: it is issued as v2 (EIP-7702), which works with the Router, once your account’s EIP-7702 migration has completed, which minting a key attempts first. If that migration does not complete, the new key is v1 again and gets this same refusal, so mint another later. Existing v1 keys keep working for credit-based (nvm:erc4337) flows until they expire. |
BCK.ROUTER.0009 | 402 | business | ❌ | Insufficient wallet balance to fund the payment | The funding source could not cover this charge. From a crypto wallet, only an MPP tempo payment is balance-checked before it is signed — a charge, or the deposit or a top-up of an MPP session: the buyer’s custodial wallet does not hold enough of the payment token on that Tempo chain (the Router never holds funds). Fund the wallet on that chain and retry. An x402 payment and an MPP evm charge are not balance-checked and never answer this code: an underfunded wallet still gets its credential, and the payment fails when the merchant settles it. On the card rail (MPP-stripe) the card issuer declined the charge: use a different card or contact the issuer — there is no wallet to top up, so ignore the on-chain advice above. In both cases this is distinct from the delegation cap (BCK.ROUTER.0003), which authorizes the spend but does not provide the funds, and from a card that needs 3-D Secure authentication (BCK.ROUTER.0011), where the card is fine and merely unauthenticated. |
BCK.ROUTER.0010 | 500 | internal | ❌ | Router could not determine the amount to charge against the delegation cap | The payment handler reported a settlement amount in cents that is not a non-negative integer, so the routing-fee arithmetic cannot compute what to reserve. This is an internal invariant violation, not a bad request — the value is produced by Nevermined, not the caller. It deliberately fails rather than defaulting to zero, which would reserve nothing and let the payment through free. DO NOT BLIND-RETRY: no budget was reserved and no payment record was written, but a payment credential WAS already minted (on the card rail, a Stripe Shared Payment Token that will auto-expire). Because no record exists, your requestId will not suppress a retry — and the cause is a deterministic defect in the rail’s approxCents derivation, so a retry re-mints a fresh credential and fails identically. Report it instead. |
BCK.ROUTER.0011 | 402 | business | ❌ | The card needs cardholder authentication (3-D Secure) before it can be used | This payment needs the cardholder to authenticate (3-D Secure / SCA) before the seller can charge it. The Router cannot complete that challenge — it needs a human at a browser, and an agent-initiated payment has none — so no usable credential was returned and NO money moved. Do NOT retry automatically: 3-D Secure is often mandated by industry rules for a given charge, in which case every retry demands it again, and each attempt creates a fresh single-use card credential that is then abandoned. It may succeed on a later attempt (whether authentication is demanded is decided per charge by the issuer, the card networks and Stripe’s own risk checks), but treat that as a manual decision, not a loop. This is distinct from the delegation cap (BCK.ROUTER.0003) and from a card that was refused for lack of funds (BCK.ROUTER.0009): the card is fine, it simply has not been authenticated for this charge. The credential Stripe created is never handed to the seller and cannot be charged while it awaits authentication; it expires on its own, at the earliest of the merchant’s quoted expiry, your delegation’s expiry, or 89 days. |
BCK.ROUTER.0012 | 400 | validation | ❌ | The 402 advertises an EIP-712 domain the settlement token does not sign under | Paying an x402 exact requirement means signing an EIP-3009 authorization under the settlement token’s own EIP-712 domain, and the seller’s 402 published an extra.name/extra.version that is not that token’s. Nevermined signs under the domain it holds for the token, never one the counterparty supplies, so it refuses rather than produce an authorization whose published terms and signature disagree. NO money moved, no credential was issued, and no delegation budget was reserved — an authorization under the wrong domain is unspendable anyway, so nothing was lost by stopping. You only see this when EVERY option in the 402 failed the check: an option with a bad domain alongside a good one is skipped, not refused. This is the seller’s bug (the values must match the token contract’s name()/version() exactly, byte for byte — Base mainnet USDC is "USD Coin", not "USDC", and a JSON number 2 is not the string "2"), so report it to them and pay a different seller meanwhile; retrying will fail identically until they fix it. Distinct from BCK.ROUTER.0001, which means your request was malformed: here the request was fine and the counterparty’s terms were not. Distinct from BCK.ROUTER.0013, which is the same check failing because NEVERMINED lacks the token’s domain — that one is ours, not the seller’s. |
BCK.ROUTER.0013 | 500 | internal | ❌ | Nevermined holds no EIP-712 signing domain for the selected settlement token | An internal invariant broke: the funding filter selected a settlement token that Nevermined recognises as fundable, but for which it holds no EIP-712 domain (name/version) to sign the EIP-3009 authorization under. That is a gap in OUR canonical token table, not a problem with your request or with the seller — do not report it to the seller. It fails rather than falling back to the domain the seller advertised, because signing under a counterparty-supplied domain is exactly the trust this check exists to remove. NO money moved, no credential was issued and no delegation budget was reserved, so nothing needs unwinding. A retry fails identically until the table is fixed, so report it rather than looping; paying a seller that settles in a different token will work in the meantime. Distinct from BCK.ROUTER.0012, where the check failed because the SELLER advertised a domain its own token does not sign under. |
BCK.ROUTER.0014 | 409 | business | ❌ | This target is a cataloged Nevermined service — invoke it through the broker | This target’s host belongs to a cataloged Nevermined service, whose upstream URL is deliberately not exposed. The Router will not pay it by raw URL: mode A (POST /api/v1/router/payments) hands YOU a credential you attach to your OWN call, and a raw mode-B target relays the response off-catalog — both put the merchant’s host on your wire, defeating the broker. If this IS the cataloged service, invoke it through the broker so the Router calls it server-side: POST /api/v1/router/route with a slug in the body, or POST /api/v1/router/svc/<catalog-slug> — find the slug on its catalog listing. If you hold an OAuth commerce grant, use POST /api/v1/router/commerce/route with a slug instead: the other two refuse a grant-bound credential (BCK.OAUTH.0030), so they are not a remedy you can follow. If the refused call was a QUOTE, re-quote by slug rather than paying: POST /api/v1/router/quote with a plain key, or POST /api/v1/router/commerce/quote with a commerce grant. The check matches the HOST, not the exact URL, so a different endpoint co-hosted on that same host is refused too even when it has no listing of its own; if that is your case, ask the vendor to list it or contact Nevermined. Raw URLs on hosts with no cataloged service are unaffected. |
BCK.ROUTER.0015 | 500 | internal | ❌ | Router could not sign the aggregate fee leg for a buyer group | The accrue-and-batch fee sweep could not produce a signed aggregate leg for a (buyer, chain, token) group — no signer authority for the wallet, the wallet could not be resolved to the group buyer, the settlement token has no canonical EIP-712 domain, or the signing window was clamped below the floor. The group stays Accrued and is retried on the next sweep; nothing was claimed and nothing is owed back. This is an internal/operator signal, never returned to a caller — the fee is collected server-side on a timer. |
BCK.ROUTER.0016 | 500 | internal | ❌ | A per-network fee-sweep floor (ROUTER_FEE_SWEEP_FLOOR_<chainId>) is misconfigured | A per-network fee-sweep floor (ROUTER_FEE_SWEEP_FLOOR_<chainId>) is set to a value that is not a positive integer (0, negative, a fraction, or unparseable). It is read as a uint256 atomic-unit threshold, so a bad value fails SAFE: no threshold sweep runs on that chain and rows keep accruing (a floor of ∞), rather than sweeping every dust group. Deduped per distinct bad value and re-emitted from RouterService.onModuleInit so it is alertable. Fix the value in the deployment (argocd) — this is an operator signal, never returned to a caller. |
BCK.ROUTER.0017 | 500 | internal | ❌ | Router aggregate fee sweep was refused after claiming a group | The accrue-and-batch fee sweep claimed a (buyer, chain, token) group Accrued → Submitted, signed one aggregate leg, submitted it, and the submitter ADJUDICATED a refusal (provably not broadcast). The group is rewound Submitted → Accrued — NOT Released — because the fee is still owed: the next sweep re-aggregates and signs a fresh leg. No cap release, no double charge. Internal/operator signal, never returned to a caller. |
BCK.ROUTER.0018 | 402 | business | ❌ | Per-call maximum is below the fee-inclusive price | The 402 quote, including the buyer fee, costs more than maxTotalCents permits — compared at 1/10,000-of-a-cent resolution, so rounding alone never triggers this. Nothing was signed, and no payment row, merchant charge or delegation reserve was made. The params field is a JSON string containing decimal strings: requiredTotalMicros is the exact fee-inclusive price in micros (1/10,000 of a cent) and requiredTotalCents is it rounded up to a whole cent; compare them with maxTotalCents, and increase the ceiling only if this additional call is intended. A retry may reuse the same requestId. |
BCK.ROUTER.0019 | 400 | business | ❌ | The service rejected the request as invalid | The service returned a non-retryable status — a client error (4xx), or a rare 3xx the Router does not follow (a 402 re-challenge and a 429 are not this code). The Router withholds the upstream response body, which can reveal the merchant host, and returns this typed error with the original status preserved (read the exact status from the params field and the HTTP status line). Build a valid request from this service’s Catalog DETAIL entry (read the service by the slug you called) — its endpoints publish requestExample and requestSchema. The bulk /catalog/ai-catalog.json discovery feed is compact: it still carries a per-endpoint requestExample, invokePath and exampleEvidence, but not the full request or response schemas. The params field is a JSON string carrying the upstream status. Do not blindly retry; correct the request first. If the response carries no X-Router-Payment-Id header, nothing was paid: send the corrected request with a fresh requestId. If it carries one, the service refused a paid request: look that payment up by your requestId with GET /api/v1/router/payments?requestId=<your requestId> (percent-encoded) before anything else, since a fresh requestId is a second purchase. Quote correlationId when reporting an issue. |
BCK.ROUTER.0020 | 502 | integration | ✅ | The service could not serve the request right now | The service returned a server error (5xx), rate-limited the request (429), or did not answer an unpaid request at all (timeout or connection failure) — an upstream/transient condition, not a problem with the request body. The Router withholds the upstream response body and headers (they can reveal the merchant host — including a 429 Retry-After), and returns this typed error with the original status preserved. The params field is a JSON string carrying the upstream status (absent when the service did not answer). Retry with backoff (exponential, especially on a 429) and the SAME requestId: the Router never pays one requestId twice. If an X-Router-Payment-Id came back, a payment is recorded: look it up first with GET /api/v1/router/payments?requestId=<your requestId> (percent-encoded). Once the service prices the call again, the same requestId answers 409 BCK.ROUTER.0002 with that paymentId instead of paying again; while the service keeps failing, it answers this code again, with no payment header. A 0020 that reached you as the result of a 202 is stored and replayed, with its X-Router-Payment-Id, for the same requestId, so reconcile it rather than retrying. A fresh requestId buys again from a service that may already have been paid: use one only for a deliberate second purchase. If it persists the service may be unavailable. The Router charges no routing fee for a call that did not deliver; whether the merchant leg itself was charged is reconciled on-chain and reported as merchantSettlementObservedAt (read alongside status) on GET /api/v1/router/payments. Quote correlationId when reporting an issue. |
BCK.ROUTER.0021 | 400 | validation | ❌ | The payment credential would overwrite a header you asked the Router to forward | The payment rail this service advertised carries its credential in a header you are already using — on the MPP rails that header is Authorization, which is also where your own merchant auth goes (headers.Authorization on POST /router/route, X-Router-Upstream-Authorization on the streaming surfaces). Sending both would silently drop yours on the paid hop, so the Router refuses instead: NO payment was minted, no delegation budget was reserved and no money moved. The params field is a JSON string naming the contested header. Fix it by telling the Router where your merchant wants the credential instead — credentialHeader in the POST /router/route body, or the X-Router-Credential-Header request header on /router/proxy and /router/svc — using the header name the service documents (a separate Payment header is the common one). If the service documents no such header, it expects the credential in Authorization itself and cannot also take your bearer there: drop your own auth for that call, or pay it over a rail whose credential travels elsewhere (x402 uses PAYMENT-SIGNATURE). Retrying unchanged fails identically. |
BCK.ROUTER.0022 | 500 | internal | ✅ | A required Router capability is unavailable | A required Router capability is not configured on this deployment. This is a configuration/wiring fault on our side, not a problem with your request; nothing was sent to a service, minted or charged by this attempt. The details or params identify service-selection or buyer-identity. Retry after the operator restores that capability; do not loop unchanged. Quote correlationId when reporting the issue. If buyer attribution is optional for your purchase, you may deliberately omit disclosure consent and make a separate request without attribution. |
BCK.ROUTER.0023 | 502 | integration | ❌ | The autoPay charge outcome could not be confirmed — reconcile before retrying | On autoPay, selection and payment run in one call. The charge outcome for this requestId could not be confirmed — either the downstream Router call did not complete cleanly after the payment was created, or the Router could not determine whether an earlier attempt on this requestId charged (including when there was none) — so the charge may or may not have landed. Do NOT retry with a fresh requestId (that could double-charge). Reconcile via GET /api/v1/router/payments, then to retry safely reuse the SAME requestId verbatim so the attempt stays idempotent. The params field is a JSON string carrying the paymentId when one is known. Quote correlationId when reporting an issue. |
BCK.ROUTER.0024 | 413 | validation | ❌ | Router JSON request body exceeds the 5242880 byte limit | Reduce the request body to 5242880 bytes or less and retry. |
BCK.ROUTER.0025 | 502 | integration | ❌ | The upstream reply was too large to deliver after a paid request; the payment may have gone through | The JSON route returns a paymentId in payment.paymentId on success; this failed JSON reply does not set X-Router-Payment-Id. Find the recorded payment by requestId via GET /api/v1/router/payments and reconcile its paymentId, status, and merchantSettlementObservedAt. Do NOT retry with a fresh requestId: the merchant may already have collected and a new requestId could double-charge. On autoPay select, the 502 carries BCK.ROUTER.0023 with paymentId in params when available. Quote correlationId when reporting an issue. |
BCK.ROUTER.0026 | 415 | validation | ❌ | The Router cannot forward this request body | The streaming surfaces (/router/svc/:slug and /router/proxy) forward a request body only when it is JSON (application/json) or a URL-encoded form (application/x-www-form-urlencoded). Any other body — multipart/form-data file uploads above all, but also text/plain, application/octet-stream or a vendor +json type — would have reached the service EMPTY, so the Router refuses it instead — as it does any body sent on a GET or HEAD, which is never forwarded. NO payment was minted, no delegation budget was reserved and no money moved. The params field is a JSON string naming the content type that was refused (contentType is null when the request sent no Content-Type, or one that is not a plain type/subtype). The remedy depends on the case: for a body on GET or HEAD, send no body (or use POST/PUT if the service takes one) — changing the content type does not help; otherwise resend the body as JSON or a URL-encoded form if the service accepts one, and note that a service that only takes a file upload cannot be paid through the Router yet. Retrying unchanged fails identically. |
BCK.ROUTER.0027 | 413 | validation | ❌ | The request body is larger than this service endpoint accepts | The catalog records a maximum request size for the endpoint you called, and your request body is larger than that. The Router refused before contacting the service: this request minted NO payment, reserved no delegation budget and moved no money (a retry whose requestId was already paid is answered with BCK.ROUTER.0002 and the original paymentId instead, never with this code). The params field is a JSON string carrying bodyBytes (the UTF-8 size of the body the Router would have sent) and maxRequestBytes (the endpoint’s limit); the same limit is published as maxRequestBytes on the endpoint in the catalog service detail (GET /api/v1/catalog/services/:slug) and in the MCP get_service result. Shrink the body below the limit (fewer or shorter inputs, or split the work into several calls), or pick a service that takes larger requests — POST /router/select with the same body skips endpoints whose limit is below it, and answers with this code (against the largest of their limits) when every otherwise-payable match is too small. Retrying unchanged fails identically. |
BCK.ROUTER.0028 | 503 | integration | ✅ | The Router could not price this call right now | The quote could not be computed because a read it depends on failed — for example the settlement token details on the payment network. This is a transient condition on our side, not a problem with your request or with the service. A quote never signs, mints or charges anything, so nothing needs unwinding: retry the quote with backoff. If it persists, quote correlationId when reporting an issue. The same condition would also fail a payment, so do not route the call meanwhile. |
BCK.ROUTER.0029 | 404 | business | ❌ | Router quote not found | The quoteId is invalid or does not belong to this account. Nothing was signed, reserved or charged. Request a new quote and use the quoteId it returns. |
BCK.ROUTER.0030 | 404 | business | ❌ | Paid result not available | There is no retained result for that paymentId under your account. A paid Router result is retained for 24 hours after the call ends, for the paying user only; after that it is deleted. Results are not retained for a streamed response that had already started when the call completed, or for a payment that was never routed through POST /router/route, /router/proxy or /router/svc. The payment record itself is unaffected: read it with GET /api/v1/router/payments. |
BCK.ROUTER.0031 | 409 | business | ❌ | Required catalog service cannot be selected | The exact opaque catalog slug named in filters.require is unavailable, unhealthy, unpayable, excluded by this request, or cannot accept the requested body. The Router failed closed before payment and did not substitute another service. Inspect params.reason, correct the slug or request, or deliberately remove require to allow normal fallback selection. |
BCK.ROUTER.0032 | 410 | business | ❌ | Router quote expired | The quoteId passed its short expiry before payment began. Nothing was signed, reserved or charged. Quote the same call again and decide against the new fee-inclusive figure. |
BCK.ROUTER.0033 | 409 | validation | ❌ | Router quote does not match this payment | The quoted target, method, headers, body, credential header, delegation, rail or exact fee-inclusive amount differs from this payment. Nothing was reserved or charged. Send the exact quoted call unchanged, or request a new quote for the changed call. |
BCK.ROUTER.0034 | 502 | integration | ❌ | The paid request got no response from the service; the payment may have gone through | The credential was sent to the service, but no response came back (timeout or connection failure). The service may already have redeemed the payment. The params field is a JSON string carrying the paymentId. Look the payment up by your requestId with GET /api/v1/router/payments?requestId=<your requestId> (percent-encoded; the payment UUID is not a lookup key) and reconcile its status and merchantSettlementObservedAt. Do NOT retry with a fresh requestId: the merchant may already have collected and a new requestId could double-charge. Quote correlationId when reporting an issue. |
BCK.ROUTER.0035 | 422 | business | ❌ | The service challenge asks for no payment | The service answered with a payment challenge for a zero amount — typically an auth-only challenge that asks the caller to sign in with a wallet rather than to pay. The Router answers one (an MPP zero-amount proof or an x402 Sign-In-With-X) only for a catalog service, on an endpoint the catalog lists with auth siwx or a declared follow-up path, when your own wallet settled a payment for that service within the follow-up window; otherwise it refuses, and nothing was signed, reserved or charged. Your request is not malformed: call the paid endpoint first, or authenticate with the service directly. |
BCK.ROUTER.0036 | 422 | business | ❌ | This service endpoint takes longer than the Router can wait for a paid call | The endpoint you called is known to answer after the Router abandons a paid call, and the merchant charges as soon as it receives the payment — so paying through the Router would charge you and deliver nothing. The Router refused before contacting the service: this request minted NO payment, reserved no delegation budget and moved no money (a retry whose requestId was already paid is answered with BCK.ROUTER.0002 and the original paymentId instead, never with this code). The params field is a JSON string carrying source: declared means the refusal is permanent; observed means it was learned from slow paid calls and lifts at liftsAt (an ISO-8601 time) — retrying before then fails identically. Pick another endpoint or service for this task. |
BCK.ROUTER.0037 | 500 | internal | ❌ | No payment handler is registered for the selected protocol | The rail selected for a quote has no registered payment handler. This is a server-side wiring defect. Operator-facing: the catalog quote refresher records the observation as indeterminate, and no client receives this code. |
BCK.ROUTER.0038 | 502 | integration | ✅ | Fee facilitator response exceeded the read cap | A fee settlement reply from the facilitator was larger than the Router reads, so it was not parsed. The fee settlement is recorded as unknown and retried. Operator-facing; no client receives this code. |
BCK.ROUTER.0039 | 500 | internal | ❌ | Router quote binding secret is not configured | JWT_SECRET_KEY is unset, so the Router cannot seal quote bindings and the API does not start. It is required by the configuration schema, so this only fires in a test double. Operator-facing; no client receives this code. |
BCK.ROUTER.0040 | 500 | internal | ❌ | Router could not read or write its MPP session channel state consistently | The Router’s record of an MPP session payment channel refused an inconsistent read or write while paying a session service: for example a second channel in a scope (payer, merchant, token, escrow and chain) that already holds one, a channel that is closing, an entry whose payer is not the channel’s owner, a malformed channel value, or channel state used outside a database transaction. It is a server-side defect, not something the caller can fix. The payment was refused before its credential reached the service, so this call moved no money and reserved no delegation budget. Do not retry automatically; report it with the correlationId. |
BCK.ROUTER.0041 | 400 | business | ❌ | This service is paid over an MPP session, which only the Router-fetched routes can pay | The service offers only an MPP session (a payment channel with a deposit and per-call vouchers). The Router must read the service’s receipt after every call to keep the channel consistent, so it pays a session only when it fetches the service itself: call it through POST /api/v1/router/route, /api/v1/router/svc/{slug} or /api/v1/router/proxy instead of minting a credential with POST /api/v1/router/payments. Nothing was signed, reserved or charged. |
BCK.ROUTER.0042 | 409 | business | ✅ | The payment channel with this service is closing | The Router’s MPP session payment channel with this service is closing, and no payment can be signed on it until the close completes. This happens when the channel’s deposit has reached its ceiling, or when the service refused the channel, a top-up of its deposit, or the payment that followed a top-up. No payment was signed, reserved or charged for this request; a top-up the Router sent the service only moves the wallet’s own funds into its channel, and they come back with the rest of the deposit at close. Retry later with the same requestId: the next call after the close opens a new channel. The close refunds the unspent part of the channel’s deposit to the wallet that funded it. |
BCK.ROUTER.0043 | 503 | integration | ✅ | The payment channel with this service is busy | The Router could not sign this payment on its MPP session payment channel with this service right now: another payment on the same channel held it too long, the wallet’s signer or balance read did not answer in time, or a top-up of the channel’s deposit could not be completed yet. This is transient. Nothing was signed, reserved or charged for this request. Retry after a few seconds with the same requestId. params.stage says which step did not answer: lock, sign, balance, or top-up (a top-up of the channel was already in flight, or the service could not be reached to take one). |
BCK.ROUTER.0044 | 422 | business | ❌ | The Router cannot collect its fee on this MPP session payment | The service is paid over an MPP session (a payment channel with a deposit and per-call vouchers). A session’s routing fee is never charged call by call: it is added up and collected later in a single transfer from the paying wallet, and here it could not be, so the Router refuses the payment instead. Nothing was signed, reserved or charged, and no payment channel was opened. The params field is a JSON string whose cause says why. org-wallet: the payment is funded by an organization wallet, which that collection cannot draw from yet; pay this service with a delegation funded by your own wallet. network: this Router deployment does not collect session fees on the service’s network; that is a configuration gap on our side, so retrying fails the same way until it changes. Pay a service on another network meanwhile, and quote correlationId when reporting it. |
BCK.ROUTER.0045 | 409 | business | ❌ | The service does not offer the payment rail you pinned | You set requireProtocol to force this call onto one payment rail (x402 or mpp), and the service’s payment challenge does not offer that rail — so the Router refused rather than pay on the other one. Nothing was signed, reserved or charged. The params field is a JSON string carrying requireProtocol (what you pinned) and offered (the rails the service’s 402 actually offered, if any). Use a service that accepts your rail, or report to the human, who can deliberately drop requireProtocol to let the Router auto-select the rail the service offers, or pin the rail it does offer. |
BCK.ROUTER.0046 | 400 | business | ❌ | The request body does not match the endpoint schema | You set validateRequestBody to have the Router check your request body before paying, and it does not match the request schema the service published for this endpoint — so the Router refused before charging, and you were not billed for a call that would have failed. Nothing was signed, reserved or charged. The params field is a JSON string carrying endpointPath (the endpoint whose schema the body failed). Fix the body to match the published schema (see requestSchema / requestExample on the endpoint in the catalog service detail, GET /api/v1/catalog/services/:slug, and in the MCP get_service result) and retry. Retrying the same body fails identically; drop validateRequestBody to let the call through unchecked. |
BCK.ROUTER.0047 | 409 | business | ❌ | This delegation does not allow session payments | The Router would pay this service over an MPP session (a payment channel: a refundable deposit leaves the wallet at the first call, and each call is paid out of it), and this delegation was created with allowSessionPayments: false. Nothing was signed, reserved or charged, and no payment channel was opened. Use a service that charges per call, or report to the human, who can deliberately drop a requireProtocol: "mpp" pin (a service that also offers x402 is then paid there) or create a new delegation that allows session payments, since a delegation cannot be edited. If the delegation is held by an app connected over OAuth, they disconnect the app in Nevermined and reconnect it with session payments allowed instead. |
BCK.ROUTER.0048 | 503 | integration | ✅ | The wallet signing key could not be read from Privy | An MPP tempo payment needs the wallet’s public key, which the Router reads once per wallet by asking Privy for one signature, and Privy did not answer (a rate limit, a server error or no response). This is transient. Nothing was signed, reserved or charged for this request, so retry after a backoff with the same requestId. |
BCK.ROUTER.0049 | 422 | business | ❌ | No payable catalog service is a close enough match for this intent | The Router scores how closely each catalog service matches your intent (a 0-100 semantic score) and chooses a payable service only when its score reaches the relevance floor. A service not yet indexed for that score can be chosen on a keyword match alone, and while semantic ranking is unavailable no service has a score, so the floor applies to none (an autoPay pick is then refused with BCK.ROUTER.0052). Every payable candidate here fell below the floor, or no catalog service matched it at all, so the Router chose none rather than name, or pay for, a service that probably does not do what you asked: nothing was charged and no payment was attempted, even with autoPay: true. The floor applies to filters.prefer too. The params field is a JSON string carrying bestSemanticScore (the closest payable candidate; absent when no catalog service matched your intent at all) and minSemanticScore (the floor). Rephrase intent to name the capability concretely (what you send and what you get back), or broaden it, or relax filters, then select again; or list candidates yourself with POST /api/v1/ard/search (search_services in the MCP) and pay one by slug. To buy a specific service regardless, name its slug in filters.require, which the floor does not apply to. The same intent is refused again. Distinct from BCK.ROUTER.0051, where a close enough match exists but is unavailable right now, from BCK.ROUTER.0053, where close enough matches exist but none returns the media you named in wantedMedia, and from BCK.ROUTER.0001, where services match but none could be chosen, nothing matched while semantic ranking is down, or the request was malformed. |
BCK.ROUTER.0050 | 409 | business | ❌ | Paid result has no content | The retained result’s state is Failed, so there is no body to download. That is the result’s own state, not the payment’s status: a call that was delivered and charged can still end this way. Read GET /api/v1/router/payments/{id}/result: a Failed result carries its failureReason, and in the rare case where the stored body could not be read for download, it answers Ready with the body. Then check deliveryStatus with GET /api/v1/router/payments?requestId=<original-requestId> (percent-encoded) before paying again. |
BCK.ROUTER.0051 | 409 | business | ✅ | The closest catalog match for this intent is unavailable right now | A catalog service that matches your intent closely enough to be chosen is unhealthy or held by moderation right now, and no other payable service matched closely enough to take its place, so the Router chose none: nothing was charged and no payment was attempted, even with autoPay: true. The cause is on the catalog side, not in your request, so rephrasing finds the same service again. Retry the same request later (keep its requestId, if it has one), since service health is re-checked periodically; or list candidates yourself with POST /api/v1/ard/search (search_services in the MCP) and pay one by slug. Distinct from BCK.ROUTER.0049, where nothing matched closely enough, and from BCK.ROUTER.0001, where nothing payable matched at all. |
BCK.ROUTER.0052 | 503 | integration | ✅ | The Router will not auto-pay a pick while semantic ranking is unavailable | Semantic ranking, which scores how closely each catalog service matches your intent, is temporarily unavailable, so the Router could only match on keywords and will not pay a keyword-only pick on its own: nothing was charged and no payment was attempted. Retry the same request later with the same requestId. Or select without autoPay, check the pick it returns, and pay it yourself by its slug (pay_service in the MCP); naming a slug in filters.require also lets autoPay pay it. |
BCK.ROUTER.0053 | 422 | business | ❌ | No catalog service close enough to this intent returns the media named in wantedMedia | You named in wantedMedia the media you need back (an image, audio or a video), and the Router chooses only a service it records as returning each of them (from some endpoint; audio beside video is not checked separately). Catalog services matched your intent closely enough, but none is recorded as returning that, so the Router chose none rather than name, or pay for, a service that may not deliver it: nothing was charged and no payment was attempted, even with autoPay: true. The params field is a JSON string carrying wantedMedia as the Router applied it: each medium once, sorted, and without audio beside video. List candidates yourself with POST /api/v1/ard/search (search_services in the MCP) and pay one by slug, or name a slug in filters.require, which this check does not apply to. Name only the media you actually need back. Distinct from BCK.ROUTER.0049, where nothing matched your intent closely enough. |
BCK.ROUTER.0056 | 422 | business | ❌ | This usage-based (x402 upto) service can be paid only from your own upgraded wallet | The service charges by usage (x402 upto): the Router authorizes a maximum through Permit2 and the merchant takes only what the call used. That needs a one-time Permit2 approval sent from the paying wallet, which the Router can send only for your own upgraded (EIP-7702) wallet, so a payment funded by an organization wallet, or by a wallet that is not upgraded, is refused, on the quote and the payment alike. Nothing was approved, signed, reserved or charged. If an organization wallet funds it, pay with an existing delegation funded by your own wallet; otherwise pick a service that charges a fixed price. |
BCK.ROUTER.0057 | 503 | integration | ✅ | The Permit2 approval this usage-based payment needs could not be made | Paying a usage-based (x402 upto) service needs your wallet to approve Permit2 once for the token, and the Router sends that approval for you. It did not complete or could not be confirmed: the bundler, paymaster, chain RPC or Privy failed, the transaction reverted, or a failure in the last 5 minutes is still in its backoff window, where a retry gets this error again without a new attempt. No payment was signed, reserved or charged. Retry after 5 minutes with the same requestId; if it persists, report it with the correlationId. |
BCK.ROUTER.0058 | 422 | business | ❌ | The Router cannot collect its fee on this usage-based (x402 upto) payment | The service charges by usage (x402 upto), so the Router’s routing fee is taken on what the merchant actually settles, later, in a single transfer with your other fees on that network. This Router deployment does not collect fees that way on the service’s network, so it refuses the payment, and its quote, instead. Nothing was approved, signed, reserved or charged. It is a configuration gap on our side, so retrying fails the same way until it changes; quote correlationId when reporting it. |