docs: sync API errors catalogue (nvm-monorepo@0075ebb)

development-guide/api-errors/codes.mdx

@@ -1,15 +1,15 @@
 ---
 title: 'API error codes'
 description: 'Catalogue of every BCK.* error code returned by the Nevermined API'
 ---
 
 Every error response from the Nevermined API carries a stable `code` (e.g. `BCK.X402.0008`). The table below enumerates every code, its HTTP status, category, canonical message, and remediation hint. Pages on this site are anchored by code — link directly to `#bck-x402-0008` from your error handlers, runbooks, or support tickets.
 
 <Note>Locked response fields are `code`, `message`, and the HTTP status. Optional fields (`hint`, `docsUrl`, `category`, `retryable`, `correlationId`) appear only when supplied. Consumers that branch only on `code` and `message` ignore the rest transparently.</Note>
 
 <Note>Beyond the catalogued codes below, any endpoint may also return a framework-level `BCK.HTTP.<status>` code (e.g. `BCK.HTTP.400` from request validation, `BCK.HTTP.429` from throttling, `BCK.HTTP.404`) for an HTTP error that carries no domain-specific code. Branch defensively — treat an unknown `BCK.HTTP.*` as its HTTP status class.</Note>
 
 ## Namespaces
 
 - [`BCK.ACCOUNT_PROVISIONING`](#bck-account_provisioning) — 2 codes
 - [`BCK.AGENT`](#bck-agent) — 12 codes
@@ -30,7 +30,7 @@
 - [`BCK.METRIC`](#bck-metric) — 5 codes
 - [`BCK.METRICS`](#bck-metrics) — 1 code
 - [`BCK.NOTIF`](#bck-notif) — 9 codes
-- [`BCK.OAUTH`](#bck-oauth) — 29 codes
+- [`BCK.OAUTH`](#bck-oauth) — 30 codes
 - [`BCK.OBSERVABILITY`](#bck-observability) — 5 codes
 - [`BCK.ORGANIZATIONS`](#bck-organizations) — 36 codes
 - [`BCK.ORG_INTEGRATION`](#bck-org_integration) — 2 codes
@@ -40,7 +40,7 @@
 - [`BCK.PLANS`](#bck-plans) — 1 code
 - [`BCK.POINT`](#bck-point) — 19 codes
 - [`BCK.PROTOCOL`](#bck-protocol) — 57 codes
-- [`BCK.ROUTER`](#bck-router) — 9 codes
+- [`BCK.ROUTER`](#bck-router) — 10 codes
 - [`BCK.STRIPE`](#bck-stripe) — 34 codes
 - [`BCK.STRIPE.CONNECT`](#bck-stripe-connect) — 8 codes
 - [`BCK.TRANSCODING`](#bck-transcoding) — 4 codes
@@ -56,57 +56,57 @@
 
 ## <span id="bck-account_provisioning"></span>`BCK.ACCOUNT_PROVISIONING`
 
 | Code | HTTP | Category | Retryable | Message | Hint |
 |---|---|---|---|---|---|
 | <a id="bck-account_provisioning-0001"></a>`BCK.ACCOUNT_PROVISIONING.0001` | 400 | validation | — | Account provisioning requires an email | Pass an email in the request body. Account provisioning is keyed on email; passwordless flows are not supported here. |
 | <a id="bck-account_provisioning-0003"></a>`BCK.ACCOUNT_PROVISIONING.0003` | 500 | integration | — | Unexpected failure during account provisioning | Inspect the underlying error in logs. Provisioning failed mid-way — usually a Privy or DB-layer error. The partial profile (if any) needs manual cleanup. |
 
 ## <span id="bck-agent"></span>`BCK.AGENT`
 
 | Code | HTTP | Category | Retryable | Message | Hint |
 |---|---|---|---|---|---|
 | <a id="bck-agent-0001"></a>`BCK.AGENT.0001` | 400 | business | — | Invalid Agent Execution Status | Provide one of the valid execution statuses (Pending, In_Progress, Completed, Failed). Other strings are rejected to keep state-machine transitions auditable. |
 | <a id="bck-agent-0002"></a>`BCK.AGENT.0002` | 500 | business | — | Error updating step agent | Inspect the underlying error in logs. The step persistence failed — usually a DB-layer constraint or stale step row. |
 | <a id="bck-agent-0003"></a>`BCK.AGENT.0003` | 403 | business | — | Unable to create task for agent | Verify the caller holds an active plan that covers this agent, and that the agent is published. |
 | <a id="bck-agent-0004"></a>`BCK.AGENT.0004` | 403 | business | — | Invalid user | Verify the authenticated user identity. The agent task endpoint requires a real (non-guest) user with a wallet. |
 | <a id="bck-agent-0005"></a>`BCK.AGENT.0005` | 403 | business | — | Unable to get task for did, task and user | Verify the (DID, taskId, user) tuple matches an existing task the user owns. Most often a stale taskId or wrong agent DID. |
 | <a id="bck-agent-0006"></a>`BCK.AGENT.0006` | 403 | business | — | Unable to find tasks by subscriber | Inspect the underlying error in logs. Subscriber-side task lookup failed — usually a DB-layer error. |
 | <a id="bck-agent-0007"></a>`BCK.AGENT.0007` | 404 | business | — | Connection not found for clientId | Verify the clientId is the value returned by the websocket handshake for this session. Clients reconnecting must rebind a fresh clientId. |
 | <a id="bck-agent-0008"></a>`BCK.AGENT.0008` | 500 | business | — | Error registering websocket connection | Inspect the underlying error in logs. Websocket registration failed — usually a Redis/queue-layer issue. |
 | <a id="bck-agent-0009"></a>`BCK.AGENT.0009` | 403 | business | — | Error creating steps for agent | Inspect the underlying error in logs. Step creation failed — verify the agent task exists and is in a state that accepts new steps. |
 | <a id="bck-agent-0010"></a>`BCK.AGENT.0010` | 403 | business | — | Task not found or completed | Verify the taskId. The task may have been marked Completed/Failed already and no longer accepts state changes. |
 | <a id="bck-agent-0011"></a>`BCK.AGENT.0011` | 500 | internal | ❌ | Agent lookup failed: agent with the given entryId not found in service layer | The service-layer findOneById returned null. The original behaviour was a generic 500; consumer code that needs 404 semantics should use BCK.PROTOCOL.0004. |
 | <a id="bck-agent-0012"></a>`BCK.AGENT.0012` | 500 | internal | ❌ | Agent DTO mapping called with a null entity | GetAgentDto.fromEntity received null. The caller should branch on the service-layer lookup result before calling fromEntity; this code only fires if a programming error leaks past that guard. |
 
 ## <span id="bck-apikey"></span>`BCK.APIKEY`
 
 | Code | HTTP | Category | Retryable | Message | Hint |
 |---|---|---|---|---|---|
 | <a id="bck-apikey-0001"></a>`BCK.APIKEY.0001` | 403 | auth | — | API Key not registered, you need to register it first | Register the API key via POST /api-keys before using it. The key signature is valid but no record exists in our DB. |
 | <a id="bck-apikey-0002"></a>`BCK.APIKEY.0002` | 404 | auth | — | API Key with given hash not found | Verify the API key value. The hashed lookup returned no row; the key may have been revoked or never registered. |
 | <a id="bck-apikey-0003"></a>`BCK.APIKEY.0003` | 404 | business | ❌ | Unable to revoke API Key | No active key matched this hash for your account — it may not exist, not belong to you, or already be revoked. |
 | <a id="bck-apikey-0004"></a>`BCK.APIKEY.0004` | 401 | auth | — | Invalid Nevermined API Key | Verify the API key value is well-formed (header.payload.signature) and not truncated. Reissue if it was rotated. |
 | <a id="bck-apikey-0006"></a>`BCK.APIKEY.0006` | 401 | auth | — | Invalid Nevermined Key Metadata | Verify the API-key payload includes the expected metadata fields (sub, iss, aud, exp). Reissue if it predates the metadata schema change. |
 | <a id="bck-apikey-0007"></a>`BCK.APIKEY.0007` | 401 | auth | — | API Key issuer does not match user address | Reissue the API key from the authenticated user’s wallet. The token’s iss claim must equal the authenticated address byte-for-byte. |
 | <a id="bck-apikey-0008"></a>`BCK.APIKEY.0008` | 403 | auth | — | API Key with hash already exists | Revoke and reissue the API key. The collision means the same hash was already stored (extremely rare; usually a duplicate-create call). |
 | <a id="bck-apikey-0009"></a>`BCK.APIKEY.0009` | 500 | auth | — | Error searching API Key transactions | Inspect the underlying error in logs. The API-key transactions query failed — usually a DB-layer error or pagination issue. |
 | <a id="bck-apikey-0010"></a>`BCK.APIKEY.0010` | 400 | validation | ❌ | Expiration date must be in the future | Provide an exp claim in the future when creating the key, or omit it for a never-expiring key. |
 | <a id="bck-apikey-0011"></a>`BCK.APIKEY.0011` | 500 | auth | — | Error searching user API Keys | Inspect the underlying error in logs. The per-user API-keys lookup failed — usually a DB-layer error. |
 | <a id="bck-apikey-0012"></a>`BCK.APIKEY.0012` | 500 | internal | — | Unexpected failure registering the API key | Inspect the underlying error in the logs by correlation id — an unexpected server-side failure during key registration, not a caller credential or signer/audience issue. |
 | <a id="bck-apikey-0013"></a>`BCK.APIKEY.0013` | 401 | auth | — | Malformed API Key payload | Verify the JWT was not truncated or tampered with in transit. Reissue the API key from the source credential store and retry. |
 | <a id="bck-apikey-0014"></a>`BCK.APIKEY.0014` | 500 | internal | ❌ | API Key claim is missing the issuer (iss) address | The validated JWT payload reached the service layer without an iss claim. Inspect the upstream guard that produced this payload — iss is mandatory for API-key issuance. |
 | <a id="bck-apikey-0015"></a>`BCK.APIKEY.0015` | 500 | auth | — | Error aggregating API Key usage | Inspect the underlying error in logs. The per-key usage aggregation query failed — usually a DB-layer error. |
 | <a id="bck-apikey-0016"></a>`BCK.APIKEY.0016` | 400 | validation | ❌ | No updatable API key fields provided | Send at least one of `name` or `apiVersion` in the PATCH body. |
 | <a id="bck-apikey-0017"></a>`BCK.APIKEY.0017` | 409 | auth | ✅ | API key has no session key for the requested network | This API key was issued without a session key for this network (#1929). Re-issue the key including this network and retry — the webapp rotates the key automatically. |
 | <a id="bck-apikey-0018"></a>`BCK.APIKEY.0018` | 400 | validation | — | Authenticated but no wallet linked to the account | Link a wallet to your account before registering an API key. Email/social sign-ins must add a wallet first. |
 | <a id="bck-apikey-0019"></a>`BCK.APIKEY.0019` | 500 | internal | — | Unexpected failure minting the API key | Minting failed server-side. Common causes: a pending DB migration on a freshly-deployed image, or a Privy/ZeroDev outage while deriving the account. Retry; if it persists, quote the correlation id. |
 
 ## <span id="bck-auth"></span>`BCK.AUTH`
 
 | Code | HTTP | Category | Retryable | Message | Hint |
 |---|---|---|---|---|---|
 | <a id="bck-auth-0001"></a>`BCK.AUTH.0001` | 500 | internal | — | Error registering API Key | Inspect the underlying error in the logs by correlation id. API-key registration failed with an unexpected server-side error (usually a DB-layer fault). |
-| <a id="bck-auth-0002"></a>`BCK.AUTH.0002` | 401 | auth | — | Authentication required: credentials are missing, expired or invalid | Send an Authorization: Bearer <token> header or a valid Nevermined API key. Anonymous access is not permitted on this endpoint. |
+| <a id="bck-auth-0002"></a>`BCK.AUTH.0002` | 401 | auth | — | Authentication required: credentials are missing, expired or invalid | Send an Authorization: Bearer &lt;token&gt; header or a valid Nevermined API key. Anonymous access is not permitted on this endpoint. |
 | <a id="bck-auth-0003"></a>`BCK.AUTH.0003` | 403 | auth | — | Forbidden: caller is not the owner of this resource and lacks an admin role | Authenticate as the resource owner or an admin who has access to it. Cross-account access is rejected unless you carry an admin role. |
 | <a id="bck-auth-0004"></a>`BCK.AUTH.0004` | 403 | auth | ❌ | Organisation admin privileges required | The caller is not an active admin of the target organisation. Prefer the more specific siblings (BCK.AUTH.0005-0009) at new throw sites; this code remains as a catch-all. |
 | <a id="bck-auth-0005"></a>`BCK.AUTH.0005` | 403 | auth | ✅ | Unable to verify organisation membership | The membership lookup itself failed (e.g. transient DB error). Check the cause field on the server log; retry once. |
@@ -115,53 +115,53 @@
 | <a id="bck-auth-0008"></a>`BCK.AUTH.0008` | 403 | auth | ❌ | Caller account is not active | The user is suspended/disabled. Reactivate via the admin UI before retrying. |
 | <a id="bck-auth-0009"></a>`BCK.AUTH.0009` | 403 | auth | ❌ | Target organisation is not active | The org has been deactivated (subscription lapsed, manual disable, etc.). Reactivate before performing admin operations. |
 | <a id="bck-auth-0010"></a>`BCK.AUTH.0010` | 403 | auth | ❌ | Direct organisation creation is restricted to internal callers | End users must upgrade via /checkout/organization-upgrade. Internal tooling must provide a valid X-Ops-Org-Create-Token header matching OPS_ORG_CREATE_TOKEN. |
 | <a id="bck-auth-0011"></a>`BCK.AUTH.0011` | 500 | internal | ❌ | Authenticated request did not yield a resolvable account address | The authenticated request reached the handler without req.address or req.smartAccountAddress populated. Two causes are common: the guard chain is misconfigured for this route, or the user has no wallet linked to their account. |
 | <a id="bck-auth-0012"></a>`BCK.AUTH.0012` | 401 | auth | ❌ | Malformed Authorization header | The Authorization header was present but not a well-formed `Bearer <token>`. Send `Authorization: Bearer <token>` (the second space-separated segment is the token). Triage tip: this code separates "garbage token" from "no token" — the latter throws BCK.AUTH.0002. |
 | <a id="bck-auth-0013"></a>`BCK.AUTH.0013` | 403 | internal | ❌ | Role guard active without @Roles metadata | A route was decorated with `@UseGuards(RolesGuard)` but no `@Roles(...)` declaration. The guard fails closed: no role list means no caller can satisfy the requirement. Add `@Roles(...)` to the handler or remove the `RolesGuard` wiring. |
 | <a id="bck-auth-0014"></a>`BCK.AUTH.0014` | 503 | integration | ✅ | Identity provider temporarily unavailable — could not verify the session | The Privy identity-token verification (`users().get({ id_token })`) could not reach Privy (rate-limited after the SDK retries, a 5xx, or a network/timeout). This is transient and does NOT mean the session is invalid — retry after a short backoff. If it persists, check the Privy status page and the service's identity-provider configuration. |
 | <a id="bck-auth-0015"></a>`BCK.AUTH.0015` | 401 | auth | — | Authentication required | Attach a valid `Authorization: Bearer <token>` (a Nevermined API key or a Privy identity token) and retry. |
 
 ## <span id="bck-billing"></span>`BCK.BILLING`
 
 | Code | HTTP | Category | Retryable | Message | Hint |
 |---|---|---|---|---|---|
 | <a id="bck-billing-0001"></a>`BCK.BILLING.0001` | 403 | auth | ❌ | Bootstrap endpoint is not enabled in this environment | The Stripe tier-products bootstrap endpoint (and /invitations/expire-stale) are gated behind `OPS_BOOTSTRAP_TOKEN`. Leave the env var unset to keep them disabled; set it to enable. |
 | <a id="bck-billing-0002"></a>`BCK.BILLING.0002` | 403 | auth | ❌ | Invalid bootstrap token | The X-Bootstrap-Token header did not match `OPS_BOOTSTRAP_TOKEN`. This endpoint is operator-only — request the token from infra. |
 | <a id="bck-billing-0003"></a>`BCK.BILLING.0003` | 503 | integration | ❌ | Stripe is not configured in this environment | `STRIPE_API_KEY` is unset, so we cannot create Stripe products. Configure Stripe credentials before running tier-products bootstrap. |
 | <a id="bck-billing-0004"></a>`BCK.BILLING.0004` | 503 | integration | ✅ | Tier catalog row missing for the requested (tier, currency, interval) combination | Run the hybrid-tier-plans bootstrap (`ENABLE_ORG_TIER_BOOTSTRAP`=true on next startup, or POST /api/v1/organizations/billing/tier-bootstrap with the ops token) to materialise the catalog rows. Returns 503 because the deployment has not been fully provisioned yet — clients may retry once the operator finishes the bootstrap. |
 | <a id="bck-billing-0010"></a>`BCK.BILLING.0010` | 400 | validation | ❌ | Invalid combination of currency and interval for org-tier checkout | USD and EUR plans must use interval=month or year (Stripe). USDC and EURC plans must use interval=one_shot (on-chain payment). Other combinations are rejected. |
 | <a id="bck-billing-0013"></a>`BCK.BILLING.0013` | 400 | business | ❌ | No active subscription found to cancel for this organization | The /billing/cancel endpoint requires an existing Stripe-backed subscription on the org. Org-tier upgrades through /billing/checkout populate this row; legacy crypto-paid orgs do not and cannot be canceled this way. |
 | <a id="bck-billing-0014"></a>`BCK.BILLING.0014` | 400 | business | ❌ | Subscription is already canceled — cannot downgrade | Stripe rejects updates on canceled subscriptions. Start a fresh Premium subscription via /checkout/organization-upgrade instead of attempting to downgrade the cancelled one. |
 | <a id="bck-billing-0015"></a>`BCK.BILLING.0015` | 400 | validation | ❌ | Invalid downgrade target tier | The /billing/downgrade endpoint only accepts Premium as the target. Use /billing/cancel to end the subscription (Lapsed/Personal are not valid downgrade targets). |
 | <a id="bck-billing-0016"></a>`BCK.BILLING.0016` | 400 | business | ❌ | No active subscription found to downgrade for this organization | The /billing/downgrade endpoint requires an existing Stripe-backed Enterprise subscription on the org. Legacy crypto-paid orgs and orgs without a tier subscription cannot be downgraded this way. |
 | <a id="bck-billing-0017"></a>`BCK.BILLING.0017` | 400 | business | ❌ | Current tier is not Enterprise — nothing to downgrade | Only Enterprise → Premium downgrades are supported. Premium and below have no paid tier above to step down from; use /billing/cancel to end the subscription instead. |
 | <a id="bck-billing-0018"></a>`BCK.BILLING.0018` | 503 | integration | ✅ | Catalog row has no Stripe priceId — Stripe products bootstrap incomplete | Run the Stripe products bootstrap (POST /api/v1/organizations/billing/bootstrap with the ops token, or `ENABLE_ORG_TIER_BOOTSTRAP`=true at startup) so the catalog row is paired with a Stripe price. Returns 503 because the deployment is partially provisioned; clients may retry once Stripe wiring lands. |
 | <a id="bck-billing-0019"></a>`BCK.BILLING.0019` | 502 | integration | ❌ | Stripe subscription has no line items | The Stripe subscription on file has zero items, which prevents a price swap during downgrade. Inspect the subscription in the Stripe dashboard — this should never happen for org-tier subs we minted ourselves. |
 | <a id="bck-billing-0020"></a>`BCK.BILLING.0020` | 502 | integration | ✅ | Stripe Checkout session created without a hosted URL | Stripe accepted the Checkout session create but returned no `url`. Treat as a transient Stripe API anomaly — retry the checkout endpoint. If it persists, inspect the Stripe Dashboard's events for the session id we return in params. |
 | <a id="bck-billing-0022"></a>`BCK.BILLING.0022` | 409 | business | ❌ | Organization already has an active subscription | A live Stripe subscription (active, trialing, or past_due) already exists for this org, so /billing/checkout would create a SECOND one and bill the org twice. Use /billing/upgrade or /billing/downgrade to change tier on the existing subscription. Re-subscribing via /checkout is only allowed once the current subscription is canceled. |
 | <a id="bck-billing-0023"></a>`BCK.BILLING.0023` | 400 | validation | ❌ | Invalid upgrade target tier | The /billing/upgrade endpoint only accepts Enterprise as the target — it swaps a Premium subscription up to Enterprise in place. To start a brand-new subscription use /checkout; to step down from Enterprise use /billing/downgrade. |
 | <a id="bck-billing-0024"></a>`BCK.BILLING.0024` | 400 | business | ❌ | No active subscription found to upgrade for this organization | The in-place /billing/upgrade requires an existing Stripe-backed Premium subscription on the org. An initial subscribe goes through /checkout; legacy crypto-paid orgs and orgs without a tier subscription cannot be upgraded this way. |
 | <a id="bck-billing-0025"></a>`BCK.BILLING.0025` | 400 | business | ❌ | Current tier is not Premium — nothing to upgrade in place | Only Premium → Enterprise in-place upgrades are supported. Not-yet-subscribed orgs start via /checkout, and Enterprise is already the top tier with nothing to upgrade to. |
 | <a id="bck-billing-0026"></a>`BCK.BILLING.0026` | 400 | business | ❌ | Subscription is already canceled — cannot upgrade | Stripe rejects updates on canceled subscriptions. Start a fresh subscription via /checkout instead of attempting to upgrade the canceled one. |
 
 ## <span id="bck-braintree"></span>`BCK.BRAINTREE`
 
 | Code | HTTP | Category | Retryable | Message | Hint |
 |---|---|---|---|---|---|
 | <a id="bck-braintree-0001"></a>`BCK.BRAINTREE.0001` | 500 | integration | — | Braintree platform gateway is not configured | The `BRAINTREE_PLATFORM_*` env vars are unset. Configure the platform-gateway credentials before enabling Braintree features. |
 | <a id="bck-braintree-0002"></a>`BCK.BRAINTREE.0002` | 400 | integration | — | Braintree charge failed | Inspect the Braintree dashboard for the transaction id in params. Common causes: processor declined, invalid CVV, or insufficient funds. |
 | <a id="bck-braintree-0003"></a>`BCK.BRAINTREE.0003` | 502 | integration | — | Braintree OAuth token refresh failed | Inspect the underlying error in logs. Token refresh failed — usually expired credentials; the merchant must re-authorize via OAuth. |
 | <a id="bck-braintree-0004"></a>`BCK.BRAINTREE.0004` | 400 | integration | — | Plan owner has not connected a Braintree merchant account | The plan owner has not connected Braintree. They must complete OAuth on the seller dashboard before their plans can be sold via Braintree. |
 | <a id="bck-braintree-0005"></a>`BCK.BRAINTREE.0005` | 400 | integration | — | Plan is not a fiat plan — cannot be purchased via Braintree | Use Braintree only for fiat plans. Crypto plans must be paid through the on-chain flow. |
 | <a id="bck-braintree-0006"></a>`BCK.BRAINTREE.0006` | 409 | integration | — | Plan owner has no Braintree merchant account connected | The plan owner has revoked or never connected their Braintree account. Ask them to reconnect before retrying the purchase. |
 | <a id="bck-braintree-0007"></a>`BCK.BRAINTREE.0007` | 400 | integration | — | Plan owner's Braintree account does not have a merchant account in the plan's currency | Ask the seller to add a Braintree merchant account in the plan’s currency, then disconnect and reconnect to refresh the cached account list. |
 | <a id="bck-braintree-0008"></a>`BCK.BRAINTREE.0008` | 400 | integration | — | Cannot create a Braintree plan in this currency: your Braintree account has no merchant account in that currency. Add one in your Braintree dashboard, then disconnect and reconnect to refresh. | Add a merchant account in the requested currency in the Braintree dashboard, then disconnect and reconnect to refresh. |
 | <a id="bck-braintree-0009"></a>`BCK.BRAINTREE.0009` | 400 | integration | — | Plan metadata is missing currency. Plans must specify a currency to be settled via Braintree. | Re-publish the plan with metadata.currency populated. Braintree cannot route the settlement without a target currency. |
 | <a id="bck-braintree-0010"></a>`BCK.BRAINTREE.0010` | 503 | integration | ✅ | Braintree/PayPal payment provider is not available in this environment | Set `BRAINTREE_MERCHANT_ID`, `BRAINTREE_PUBLIC_KEY`, and `BRAINTREE_PRIVATE_KEY` in the deployment env. Returns 503 because the route is reachable only after the operator wires Braintree up. |
 
 ## <span id="bck-budgets"></span>`BCK.BUDGETS`
 
 | Code | HTTP | Category | Retryable | Message | Hint |
 |---|---|---|---|---|---|
 | <a id="bck-budgets-0001"></a>`BCK.BUDGETS.0001` | 403 | business | ❌ | Group budgets are not available on this organization tier | Group budgets require a Premium or Enterprise organization. Upgrade the organization tier to set spend budgets on groups. |
 | <a id="bck-budgets-0002"></a>`BCK.BUDGETS.0002` | 404 | business | ❌ | Group budget not found | No budget with that id for this group. Create one with POST /organizations/:orgId/groups/:groupId/budgets. |
@@ -172,30 +172,30 @@
 
 ## <span id="bck-catalog"></span>`BCK.CATALOG`
 
 | Code | HTTP | Category | Retryable | Message | Hint |
 |---|---|---|---|---|---|
 | <a id="bck-catalog-0001"></a>`BCK.CATALOG.0001` | 404 | business | ❌ | Agent service not found | No listed catalog service matches that slug. Slugs are case-sensitive; unlisted services are not exposed. |
 | <a id="bck-catalog-0002"></a>`BCK.CATALOG.0002` | 500 | internal | ✅ | Failed to read the agent services catalog | Transient server-side error reading the catalog (list, detail, or categories); safe to retry. Query inputs are validated upstream, so this is not a bad-request issue. |
 | <a id="bck-catalog-0003"></a>`BCK.CATALOG.0003` | 400 | validation | ❌ | Invalid catalog filter | The `protocol` filter must be one of: x402, mpp, rest, a2a, other. |
 
 ## <span id="bck-common"></span>`BCK.COMMON`
 
 | Code | HTTP | Category | Retryable | Message | Hint |
 |---|---|---|---|---|---|
 | <a id="bck-common-0001"></a>`BCK.COMMON.0001` | 500 | internal | — | Unable to initialize Nevermined instance | Inspect the API logs around startup. The Nevermined SDK could not initialise — usually a misconfigured RPC provider, missing wallet seed, or a chain-config mismatch. |
 | <a id="bck-common-0002"></a>`BCK.COMMON.0002` | 500 | internal | — | Unable to generate session key | Inspect the underlying error in logs. The Nevermined SDK could not derive a session signer — usually a wallet/keystore configuration problem. |
 | <a id="bck-common-0003"></a>`BCK.COMMON.0003` | 500 | internal | — | Unable to retrieve fees information from Nevermined | Inspect the underlying error in logs. The protocol fee lookup failed — verify chain connectivity and that the FeeController contract is reachable. |
 | <a id="bck-common-0004"></a>`BCK.COMMON.0004` | 500 | internal | — | Unable to calculate Asset Price | Inspect the underlying error in logs. The pricing helper failed — usually a missing/invalid plan price metadata or a chain-side revert. |
 | <a id="bck-common-0005"></a>`BCK.COMMON.0005` | 500 | internal | — | Unable to load NFT Contract | Inspect the underlying error in logs. The NFT contract handle could not be resolved — verify the address registered in protocol config matches the deployed contract. |
 | <a id="bck-common-0006"></a>`BCK.COMMON.0006` | 500 | internal | — | Unable to register Credits Plan on Nevermined | Inspect the underlying error in logs. Credit plan registration failed at protocol or SDK layer — re-run after fixing the cause; the partial plan row (if any) needs manual cleanup. |
 | <a id="bck-common-0007"></a>`BCK.COMMON.0007` | 500 | internal | — | Unable to register Time Plan on Nevermined | Inspect the underlying error in logs. Time plan registration failed at protocol or SDK layer — re-run after fixing the cause; the partial plan row (if any) needs manual cleanup. |
 | <a id="bck-common-0008"></a>`BCK.COMMON.0008` | 500 | internal | — | Unable to register Points event in the database | Inspect the underlying error in logs. The points-event insert failed — typically a DB-side constraint or connectivity issue. Re-run idempotently or backfill manually. |
 | <a id="bck-common-0009"></a>`BCK.COMMON.0009` | 500 | internal | — | Unable to register API Key usage in the database | Inspect the underlying error in logs. The API-key usage insert failed — typically a DB-side constraint or connectivity issue. |
 | <a id="bck-common-0010"></a>`BCK.COMMON.0010` | 500 | internal | — | Unable to register AI Agent | Inspect the underlying error in logs. Agent registration failed at protocol or DB layer. The partial row (if any) should be removed before retry. |
 | <a id="bck-common-0011"></a>`BCK.COMMON.0011` | 500 | internal | — | Unable to register File asset | Inspect the underlying error in logs. File asset registration failed — usually a storage-layer or DDO-write error. |
 | <a id="bck-common-0012"></a>`BCK.COMMON.0012` | 500 | internal | — | Unable to generate access token to AI Agent | Inspect the underlying error in logs. Access-token minting failed — verify the agent is registered and the requesting user has a valid plan. |
 | <a id="bck-common-0013"></a>`BCK.COMMON.0013` | 404 | internal | — | Unable to resolve DDO from DID | Verify the DID is well-formed and exists in metadata. The DDO resolver returned no document; this is a 404 by design. |
 | <a id="bck-common-0014"></a>`BCK.COMMON.0014` | 404 | internal | — | Plan not found | Verify the planId. The plan may have been deleted or never registered. Common causes: stale link, environment mismatch (sandbox vs live). |
 | <a id="bck-common-0015"></a>`BCK.COMMON.0015` | 500 | internal | — | Unable to get the Plan balance | Inspect the underlying error in logs. Balance lookup failed — usually a chain RPC or contract-call revert. |
 | <a id="bck-common-0016"></a>`BCK.COMMON.0016` | 500 | internal | — | Unable to order the subscription | Inspect the underlying error in logs. Subscription ordering failed — verify the buyer has sufficient balance and the plan is active. |
 | <a id="bck-common-0017"></a>`BCK.COMMON.0017` | 500 | internal | — | There are no files associated to the file asset | Re-publish the asset with at least one file entry, or use a different agent endpoint that does not require files. |
@@ -210,7 +210,7 @@
 | <a id="bck-common-0026"></a>`BCK.COMMON.0026` | 400 | validation | — | Invalid uint256 identifier (must be a decimal string in [0, 2^256 - 1]) | Provide a decimal-string uint256 in the highlighted field (no 0x prefix, no scientific notation). Plan IDs and agent IDs use this format end-to-end. |
 | <a id="bck-common-0027"></a>`BCK.COMMON.0027` | 409 | business | ❌ | Resource already exists (database unique constraint violated) | A record with the same unique key already exists. Either update the existing record or use a different identifier. |
 | <a id="bck-common-0028"></a>`BCK.COMMON.0028` | 409 | business | ❌ | Referenced resource does not exist (foreign key violation) | The request references an entity (plan, agent, user, organisation) that does not exist or has been deleted. Verify the referenced ID. |
 | <a id="bck-common-0029"></a>`BCK.COMMON.0029` | 503 | integration | ✅ | Database temporarily unavailable | The database is being restarted or is under maintenance. Retry the request after a short backoff. |
 | <a id="bck-common-0030"></a>`BCK.COMMON.0030` | 500 | internal | ❌ | Invalid ECDSA public key format | The provider public key did not match the expected 65-byte uncompressed prefix (0x04 + x + y). Inspect getProviderPublicKey() output. |
 | <a id="bck-common-0031"></a>`BCK.COMMON.0031` | 500 | internal | ❌ | Invalid ECDSA public key length | After normalising, the provider public key was not 128 hex characters (64 bytes). Inspect getProviderPublicKey() output and the upstream key derivation. |
 | <a id="bck-common-0032"></a>`BCK.COMMON.0032` | 500 | internal | ❌ | Provider public key not available for JWKS endpoint | NeverminedService.getProviderPublicKey() returned empty. Verify the node wallet seed configuration and that the service initialised successfully at startup. |
@@ -219,62 +219,62 @@
 
 ## <span id="bck-credits"></span>`BCK.CREDITS`
 
 | Code | HTTP | Category | Retryable | Message | Hint |
 |---|---|---|---|---|---|
-| <a id="bck-credits-0001"></a>`BCK.CREDITS.0001` | 400 | business | — | Mint amount must be positive | Send mint amount > 0. Zero or negative mints are rejected; cleanup of bad lots must happen through a refund path. |
-| <a id="bck-credits-0002"></a>`BCK.CREDITS.0002` | 400 | business | — | Burn amount must be positive | Send burn amount > 0. Zero or negative burns are rejected. |
+| <a id="bck-credits-0001"></a>`BCK.CREDITS.0001` | 400 | business | — | Mint amount must be positive | Send mint amount &gt; 0. Zero or negative mints are rejected; cleanup of bad lots must happen through a refund path. |
+| <a id="bck-credits-0002"></a>`BCK.CREDITS.0002` | 400 | business | — | Burn amount must be positive | Send burn amount &gt; 0. Zero or negative burns are rejected. |
 | <a id="bck-credits-0003"></a>`BCK.CREDITS.0003` | 402 | business | — | Insufficient credits for plan | Buy or top up credits before retrying. The buyer wallet does not hold enough credits for the requested redemption. |
-| <a id="bck-credits-0004"></a>`BCK.CREDITS.0004` | 400 | business | — | Refund amount must be positive | Send refund amount > 0. Zero or negative refunds are rejected; they are also bounded by the original mint amount. |
+| <a id="bck-credits-0004"></a>`BCK.CREDITS.0004` | 400 | business | — | Refund amount must be positive | Send refund amount &gt; 0. Zero or negative refunds are rejected; they are also bounded by the original mint amount. |
 | <a id="bck-credits-0005"></a>`BCK.CREDITS.0005` | 500 | business | — | Credit lots do not satisfy the burned amount — FIFO invariant violated | Inspect the underlying error and the planId/userId in params. The FIFO credit-lots ledger could not satisfy the burn — this indicates a data-integrity issue; do not retry blindly. |
 | <a id="bck-credits-0006"></a>`BCK.CREDITS.0006` | 500 | internal | ❌ | Cannot enqueue on-chain order mirror without a corresponding minted credit lot | enqueueFiatOrderMirror must be called after a successful creditsService.mint with the same sourceTx. This usually indicates an out-of-order call by a service, not a runtime data issue. |
 
 ## <span id="bck-delegation"></span>`BCK.DELEGATION`
 
 | Code | HTTP | Category | Retryable | Message | Hint |
 |---|---|---|---|---|---|
 | <a id="bck-delegation-0001"></a>`BCK.DELEGATION.0001` | 404 | business | ❌ | Payment method not found | Verify the paymentMethodId. The payment method may have been removed or never existed. |
 | <a id="bck-delegation-0002"></a>`BCK.DELEGATION.0002` | 404 | business | ❌ | Delegation not found | Verify the delegationId. The delegation may have been revoked, expired, or never existed. |
 | <a id="bck-delegation-0003"></a>`BCK.DELEGATION.0003` | 400 | validation | ❌ | Unknown payment method provider | The ?provider= query param must be one of the supported providers (stripe, braintree, erc4337, visa, vgs). Omit it to list methods from every provider. |
 | <a id="bck-delegation-0004"></a>`BCK.DELEGATION.0004` | 400 | validation | ❌ | Required delegation input is missing | Provide both `provider` (stripe \| braintree \| erc4337 \| visa) and `currency` (usd \| eur \| usdc \| eurc) when creating a delegation. Both are required — the backend no longer defaults them. The `details` field names the specific missing input. |
 | <a id="bck-delegation-0005"></a>`BCK.DELEGATION.0005` | 422 | business | ❌ | Card is not network-token chargeable | A `provider: "vgs"` delegation needs a portable credential (a CRD canonical card with an ACTIVE network token). The referenced card has none — it was enrolled with the canonical-credential flag off, its network-token provision failed at enrol, or the token was revoked. Re-enrol the card via the unified VGS-Collect enroll endpoint to (re)provision a network token, then retry. |
 | <a id="bck-delegation-0006"></a>`BCK.DELEGATION.0006` | 422 | business | ❌ | Plan payment provider is not network-token capable | A `provider: "vgs"` delegation is plan-agnostic and settles through the plan’s `fiatPaymentProvider`, resolved at CHARGE time (#2082) — but that plan’s provider is not in the network-token-capable acquirer set (currently stripe, braintree). The plan metadata likely carries an unexpected/unsupported `fiatPaymentProvider`. Fix the plan’s payment provider, then retry. |
 | <a id="bck-delegation-0007"></a>`BCK.DELEGATION.0007` | 400 | business | ❌ | Requested provider does not match the stored payment method | The create-delegation request declared a `provider` that does not match the provider the referenced payment method was enrolled under (e.g. requesting `stripe` for a card enrolled via the unified VGS-Collect rail, whose provider is `vgs`). Send the `provider` that matches the payment method — the value the delegation payment-methods list returns for it. |
 | <a id="bck-delegation-0008"></a>`BCK.DELEGATION.0008` | 422 | business | ❌ | Delegation cannot be settled via card | This delegation was created on the crypto (`erc4337`) rail, which settles on-chain and has no card payment provider — a `nvm:card-delegation` settle cannot charge it (#2627). Settle a crypto delegation through the `nvm:erc4337` scheme instead, or create a card delegation (stripe/braintree/visa/vgs) for card settlement. |
 
 ## <span id="bck-entitlements"></span>`BCK.ENTITLEMENTS`
 
 | Code | HTTP | Category | Retryable | Message | Hint |
 |---|---|---|---|---|---|
 | <a id="bck-entitlements-0001"></a>`BCK.ENTITLEMENTS.0001` | 403 | business | ❌ | Resource cap reached for your current workspace. Upgrade to unlock higher limits. | The active workspace (personal or Premium org) has hit its agent/plan cap. Response `params.cap` and `params.current` carry the limit and current count; switch workspaces, deactivate unused resources, or upgrade the org tier to lift the cap. |
 | <a id="bck-entitlements-0002"></a>`BCK.ENTITLEMENTS.0002` | 403 | business | ❌ | Organization is not active. Reactivate the subscription before creating new resources. | The target workspace has a lapsed subscription (paid period ended without renewal, or admin override). Existing resources remain visible but new agents/plans cannot be registered until the org is reactivated via the Billing page. |
 
 ## <span id="bck-groups"></span>`BCK.GROUPS`
 
 | Code | HTTP | Category | Retryable | Message | Hint |
 |---|---|---|---|---|---|
 | <a id="bck-groups-0001"></a>`BCK.GROUPS.0001` | 403 | business | ❌ | Organization groups are not available for this organization tier | Groups require a Premium or Enterprise organization. Upgrade the organization tier to create and manage groups. |
 | <a id="bck-groups-0002"></a>`BCK.GROUPS.0002` | 404 | business | ❌ | Group not found | The groupId does not exist in this organization, or has been deactivated. List groups to get valid ids. |
 | <a id="bck-groups-0003"></a>`BCK.GROUPS.0003` | 422 | business | ❌ | Groups cap reached: cannot create more groups for this organization | The active-group cap for this tier has been reached. Deactivate an unused group or upgrade the tier to create more. |
 | <a id="bck-groups-0004"></a>`BCK.GROUPS.0004` | 409 | business | ❌ | Member already belongs to an active group | A member can belong to at most one active group. Remove the member from their current group before adding them to another. |
 | <a id="bck-groups-0005"></a>`BCK.GROUPS.0005` | 404 | business | ❌ | Organization member not found | The memberId is not an active member of this organization. List members to get valid ids. |
 | <a id="bck-groups-0006"></a>`BCK.GROUPS.0006` | 404 | business | ❌ | Member is not in this group | The member is not an active member of the specified group; nothing to remove. |
 | <a id="bck-groups-0007"></a>`BCK.GROUPS.0007` | 404 | business | ❌ | Payment method not found | The payment method id does not match an enrolled card you own. Enroll a card first, then share it with the group. |
 | <a id="bck-groups-0008"></a>`BCK.GROUPS.0008` | 422 | validation | ❌ | Only card payment methods can be shared with a group | Crypto (wallet) instruments cannot be shared as a group payment method in this phase; use an enrolled card. |
 | <a id="bck-groups-0009"></a>`BCK.GROUPS.0009` | 409 | business | ❌ | Payment method is already shared with a group | A payment method belongs to at most one group. Remove it from its current group before sharing it elsewhere. |
 | <a id="bck-groups-0010"></a>`BCK.GROUPS.0010` | 404 | business | ❌ | Group payment method not found | This payment method is not shared with the specified group; nothing to remove. |
 | <a id="bck-groups-0011"></a>`BCK.GROUPS.0011` | 422 | validation | ❌ | Payment method is bound to a specific API key and cannot be shared with a group | This card is locked to one of your API keys, so group members could not charge it. Unbind the API key from the card before sharing it with the group. |
 | <a id="bck-groups-0012"></a>`BCK.GROUPS.0012` | 409 | business | ❌ | Card is not associated with this organization | Associate the card with this organization first (a personal card cannot be shared with an organization group). Only a card whose orgId matches this organization can fund its group budgets. |
 
 ## <span id="bck-guest"></span>`BCK.GUEST`
 
 | Code | HTTP | Category | Retryable | Message | Hint |
 |---|---|---|---|---|---|
 | <a id="bck-guest-0001"></a>`BCK.GUEST.0001` | 400 | validation | ❌ | Invalid guest account request | Check the request body — guest provisioning requires either fingerprint or externalId. |
 | <a id="bck-guest-0002"></a>`BCK.GUEST.0002` | 500 | business | — | Failed to provision guest account | Inspect the underlying error in logs. Guest provisioning failed mid-way — usually a DB-layer or Privy issue. |
 
 ## <span id="bck-invitations"></span>`BCK.INVITATIONS`
 
 | Code | HTTP | Category | Retryable | Message | Hint |
 |---|---|---|---|---|---|
 | <a id="bck-invitations-0001"></a>`BCK.INVITATIONS.0001` | 422 | business | ❌ | Seat cap reached: cannot invite more members to this organization | The seat cap (members + pending invitations) for this tier has been reached. Remove pending invitations, deactivate inactive members, or upgrade the tier to invite more seats. |
 | <a id="bck-invitations-0002"></a>`BCK.INVITATIONS.0002` | 409 | business | ❌ | A pending invitation already exists for this email in the organization | Revoke the existing invitation (or wait for the invitee to accept it) before sending a new one. Resending overwrites the role; revoking removes it entirely. |
@@ -284,7 +284,7 @@
 
 ## <span id="bck-legal_docs"></span>`BCK.LEGAL_DOCS`
 
 | Code | HTTP | Category | Retryable | Message | Hint |
 |---|---|---|---|---|---|
 | <a id="bck-legal_docs-0001"></a>`BCK.LEGAL_DOCS.0001` | 404 | business | — | Unknown legal document | Verify the legal-document slug (terms, privacy, etc.). Unknown slugs are rejected to surface typos early. |
 | <a id="bck-legal_docs-0002"></a>`BCK.LEGAL_DOCS.0002` | 404 | business | — | Unknown legal document version | Verify the document version. Unknown versions are rejected; ask the admin to publish the version first. |
@@ -295,23 +295,23 @@
 
 ## <span id="bck-metric"></span>`BCK.METRIC`
 
 | Code | HTTP | Category | Retryable | Message | Hint |
 |---|---|---|---|---|---|
 | <a id="bck-metric-0001"></a>`BCK.METRIC.0001` | 500 | integration | — | Error registering asset access | Inspect the underlying error in logs. Asset-access metric write failed — usually a DB/queue layer issue. Metrics are best-effort; the user request still completed. |
 | <a id="bck-metric-0002"></a>`BCK.METRIC.0002` | 404 | integration | — | Error search asset metrics | Verify the asset DID and that metrics retention has not pruned the rows. Empty metric lookups return 404 by design. |
 | <a id="bck-metric-0003"></a>`BCK.METRIC.0003` | 404 | integration | — | Error getting info from metrics service for | Inspect the underlying error in logs. Upstream metrics service did not respond — verify the metrics service URL and that it is reachable from the API. |
 | <a id="bck-metric-0004"></a>`BCK.METRIC.0004` | 500 | integration | — | Error getting balance for account | Inspect the underlying error in logs. Account-balance metric query failed — usually a DB or chain-RPC issue. |
 | <a id="bck-metric-0005"></a>`BCK.METRIC.0005` | 500 | integration | — | Error getting total hits for account | Inspect the underlying error in logs. Hits-counter aggregation query failed — usually a DB-layer error. |
 
 ## <span id="bck-metrics"></span>`BCK.METRICS`
 
 | Code | HTTP | Category | Retryable | Message | Hint |
 |---|---|---|---|---|---|
-| <a id="bck-metrics-0001"></a>`BCK.METRICS.0001` | 401 | auth | ❌ | Unauthorized metrics scrape | The internal metrics endpoint is token-protected (METRICS_SCRAPE_TOKEN is set). Send "Authorization: Bearer <token>" matching the configured scrape token. |
+| <a id="bck-metrics-0001"></a>`BCK.METRICS.0001` | 401 | auth | ❌ | Unauthorized metrics scrape | The internal metrics endpoint is token-protected (METRICS_SCRAPE_TOKEN is set). Send "Authorization: Bearer &lt;token&gt;" matching the configured scrape token. |
 
 ## <span id="bck-notif"></span>`BCK.NOTIF`
 
 | Code | HTTP | Category | Retryable | Message | Hint |
 |---|---|---|---|---|---|
 | <a id="bck-notif-0001"></a>`BCK.NOTIF.0001` | 404 | integration | — | Unable to find notification by id | Verify the notification id. The notification may have been deleted or never existed. |
 | <a id="bck-notif-0002"></a>`BCK.NOTIF.0002` | 404 | integration | — | Error searching for notifications | Inspect the underlying error in logs. Notification search failed — usually a DB-layer error or invalid query filter. |
@@ -321,55 +321,56 @@
 | <a id="bck-notif-0006"></a>`BCK.NOTIF.0006` | 404 | integration | — | Error searching for notifications filtered by receiver | Verify the receiver address. Empty result sets surface as 404 by design. |
 | <a id="bck-notif-0007"></a>`BCK.NOTIF.0007` | 500 | integration | — | Resend API Key or Email Sender not set | Configure `RESEND_API_KEY` and `EMAIL_SENDER` in the deployment env. Email notifications are disabled until both are present. |
 | <a id="bck-notif-0008"></a>`BCK.NOTIF.0008` | 500 | integration | — | Error sending email notification | Inspect Resend dashboard logs for the sender/recipient in params. Common causes: invalid recipient address, domain not verified, or quota exhaustion. |
 | <a id="bck-notif-0009"></a>`BCK.NOTIF.0009` | 403 | business | ❌ | The user doesnt own this notification | Notifications are scoped to a single recipient; only the owner can act on them. Re-authenticating as the same caller will not help. |
 
 ## <span id="bck-oauth"></span>`BCK.OAUTH`
 
 | Code | HTTP | Category | Retryable | Message | Hint |
 |---|---|---|---|---|---|
 | <a id="bck-oauth-0001"></a>`BCK.OAUTH.0001` | 404 | auth | ❌ | OAuth resource not found | Verify the agentId or client identifier in the OAuth request. |
 | <a id="bck-oauth-0002"></a>`BCK.OAUTH.0002` | 400 | auth | ❌ | Invalid OAuth request | Check the request parameters — typically the redirect_uri, scope, or grant_type does not match the registered client. Prefer the more specific BCK.OAUTH.0003-0006 siblings at new throw sites. |
 | <a id="bck-oauth-0003"></a>`BCK.OAUTH.0003` | 400 | business | ❌ | No payment plans available for agent | The target agent has no published plans the caller can purchase. Publish a plan first, or pass an explicit plan_id that the caller already owns. |
 | <a id="bck-oauth-0004"></a>`BCK.OAUTH.0004` | 400 | auth | ❌ | Invalid or expired authorization code | Authorization codes are single-use and short-lived. Restart the flow from /authorize to obtain a fresh code, and ensure the code_verifier matches the original PKCE code_challenge. |
 | <a id="bck-oauth-0005"></a>`BCK.OAUTH.0005` | 400 | auth | ❌ | Resource mismatch between token request and authorization code | The `resource` parameter on /token does not match the value bound to the authorization code. Resend with the same `resource` you used on /authorize. |
 | <a id="bck-oauth-0006"></a>`BCK.OAUTH.0006` | 400 | auth | ❌ | User profile not found for the authorization code | The user bound to the authorization code no longer exists in our DB (deleted profile, or environment mismatch). Restart the flow with a valid signed-in user. |
 | <a id="bck-oauth-0007"></a>`BCK.OAUTH.0007` | 400 | auth | ❌ | Authorize endpoint requires an authenticated user | The POST /oauth/authorize endpoint expects a signed-in user (NVM API key hash or Privy identity token). Authenticate before requesting an authorization code. |
 | <a id="bck-oauth-0008"></a>`BCK.OAUTH.0008` | 400 | business | ❌ | Requested resource is not covered by this authorization | RFC 8707 invalid_target: the `resource` you requested at /oauth/token maps to a credential the binding does not cover (e.g. an x402 resource on a binding with no spend delegation). The authorization code is single-use and has already been consumed, so it cannot be retried — restart the flow at POST /oauth/authorize requesting a `resource` the binding covers (or omit `resource` to receive its default credential). |
 | <a id="bck-oauth-0009"></a>`BCK.OAUTH.0009` | 401 | auth | ❌ | Credential revoked | The authorization behind this credential was revoked (the human withdrew consent via /oauth/revoke). Every credential minted from that binding — API key and x402 permission — is now invalid. Restart the flow at POST /oauth/authorize to obtain a new credential. |
 | <a id="bck-oauth-0010"></a>`BCK.OAUTH.0010` | 401 | auth | ❌ | Credential presented outside its resource audience | This credential was minted (RFC 8707) for a specific `resource` and is confined to it, but was presented to a different Nevermined API deployment/audience than the one it was authorized for. Restart the flow at POST /oauth/authorize requesting the `resource` you are calling. |
 | <a id="bck-oauth-0011"></a>`BCK.OAUTH.0011` | 400 | auth | ❌ | Invalid refresh token | OAuth `invalid_grant`: the refresh token is unknown, expired, already rotated (one-time use — replaying it revokes the whole chain), revoked, or was issued to a different client. Restart at POST /oauth/authorize to obtain a fresh token pair. |
 | <a id="bck-oauth-0012"></a>`BCK.OAUTH.0012` | 400 | business | ❌ | Delegation expired | OAuth `invalid_grant` (sub-reason `delegation_expired`): the spend delegation this binding relies on has expired, so no new credential can be minted from it. The human must re-authorize a fresh delegation at POST /oauth/authorize. |
 | <a id="bck-oauth-0013"></a>`BCK.OAUTH.0013` | 400 | business | ❌ | Budget exhausted | OAuth `invalid_grant` (sub-reason `budget_exhausted`): the plan credits / delegation funding this binding are spent — either the amount cap (`spendingLimitCents`) or the transaction-count cap (`maxTransactions`) is reached — so re-minting is refused. Top up the plan (or authorize a new delegation) and retry, or restart at POST /oauth/authorize. |
 | <a id="bck-oauth-0014"></a>`BCK.OAUTH.0014` | 400 | business | ❌ | Delegation revoked | OAuth `invalid_grant` (sub-reason `delegation_revoked`): the spend delegation this binding relies on has been revoked, so no new credential can be minted from it. The human must authorize a fresh delegation at POST /oauth/authorize. |
 | <a id="bck-oauth-0015"></a>`BCK.OAUTH.0015` | 404 | business | ❌ | AgentBinding not found | No AgentBinding with this id belongs to the signed-in user. It may not exist or may belong to another user (#2401 Connected agents). Refresh the list and retry. |
 | <a id="bck-oauth-0016"></a>`BCK.OAUTH.0016` | 400 | auth | ❌ | Unknown OAuth client | The `client_id` is not a registered OAuth client. Clients are provisioned out-of-band (Dynamic Client Registration is not supported). Note (#2235 G3): `client_id` identifies the OAuth client — a connector or the first-party webapp — NOT the agent; the target agent goes in `agent_id`. |
 | <a id="bck-oauth-0017"></a>`BCK.OAUTH.0017` | 400 | auth | ❌ | redirect_uri not registered for this client | RFC 6749 §4.1.3: the `redirect_uri` must EXACTLY match one registered for the `client_id` (no wildcard or prefix match). Send a redirect URI already registered for the client. |
 | <a id="bck-oauth-0018"></a>`BCK.OAUTH.0018` | 400 | auth | ❌ | Missing required parameter: agent_id | An agent-specific authorization requires `agent_id` (the target agent) in addition to `client_id` (the connector). Include `agent_id` in the connector's authorize URL. #2235 G3. |
 | <a id="bck-oauth-0019"></a>`BCK.OAUTH.0019` | 400 | business | ❌ | Plan is not associated with the requested agent | The supplied `plan_id` does not belong to the target `agent_id`. Pass a plan registered for that agent, or omit `plan_id` to use the agent's default plan. |
 | <a id="bck-oauth-0020"></a>`BCK.OAUTH.0020` | 400 | auth | ❌ | Invalid or expired user code | The code may be mistyped, expired, or already used. Ask the agent to start a new device authorization and read out the fresh code. |
 | <a id="bck-oauth-0021"></a>`BCK.OAUTH.0021` | 400 | auth | ✅ | Authorization pending | RFC 8628 authorization_pending: the user has not yet approved. Keep polling /oauth/token at the interval from the device authorization response. |
 | <a id="bck-oauth-0022"></a>`BCK.OAUTH.0022` | 400 | auth | ✅ | Polling too fast | RFC 8628 slow_down: you polled faster than the interval. Increase your poll interval by 5 seconds and continue. |
 | <a id="bck-oauth-0023"></a>`BCK.OAUTH.0023` | 400 | auth | ❌ | Device code expired | RFC 8628 expired_token: the device_code/user_code lifetime elapsed before approval. Start a new device authorization. |
 | <a id="bck-oauth-0024"></a>`BCK.OAUTH.0024` | 400 | auth | ❌ | The user denied the authorization request | RFC 8628 access_denied: the human declined at the verification page. Do not retry with this device_code. |
 | <a id="bck-oauth-0025"></a>`BCK.OAUTH.0025` | 403 | auth | ❌ | Account-level authorization requires a verified client | This client is enabled for account-level connect but is not `verified`. Account-wide spending authority is granted only to verified clients (#2541 / G3 F2/F4). Use an agent-specific authorization (include `agent_id`) instead, or have the client verified. |
 | <a id="bck-oauth-0026"></a>`BCK.OAUTH.0026` | 400 | auth | ❌ | Account-level authorization requires funding details | An account-level connect is delegation-backed: it must carry the spend cap it binds to — `provider`, `provider_payment_method_id`, `spending_limit_cents`, `duration_secs`, and `currency`. Enrol a card and set a cap before authorizing. #2541. |
 | <a id="bck-oauth-0027"></a>`BCK.OAUTH.0027` | 403 | auth | ❌ | This credential cannot create authorizations or spend mandates | An `account_access` credential is minted to SPEND against the card delegation it is bound to (via x402), NOT to run a new authorization ceremony or create another card mandate. It could otherwise mint itself a second, larger mandate on the same card, defeating the consented cap. Authorize from the human browser session, or use an agent-specific key for agent flows. #2574 B1. |
 | <a id="bck-oauth-0029"></a>`BCK.OAUTH.0029` | 500 | internal | ❌ | Internal error creating the agent binding | A server-side data-integrity condition — an agent-specific (credits_purchase) binding reached persistence without an agent id, which the database CHECK forbids. No action is required from the caller; inspect the API logs (the failing authorization request id is on the error `details`/`params`). #2578. |
 | <a id="bck-oauth-0030"></a>`BCK.OAUTH.0030` | 403 | auth | ❌ | This credential cannot use the Router spend rails or create delegations | An OAuth-minted credential (`credits_purchase` or `account_access`) may not call `POST /router/{payments,route,proxy}` or `POST /delegation/create`: those routes sign from the account wallet, outside the session-key policy the credential advertises — and a `credits_purchase` key owns no delegation, so any delegation it reaches was never consented for. Use a plain API key from the account owner, or the credential’s own x402 spend rail. #2575. |
+| <a id="bck-oauth-0031"></a>`BCK.OAUTH.0031` | 400 | auth | ❌ | Invalid client metadata document | The `client_id` was treated as a CIMD (Client ID Metadata Document) URL but did not resolve to a valid document. It must be an https URL on a public host that returns a JSON document whose `client_id` equals the URL and which declares a non-empty `client_name` and `redirect_uris`. If your host uses static registration instead, register it out-of-band and use its issued `client_id`. |
 
 ## <span id="bck-observability"></span>`BCK.OBSERVABILITY`
 
 | Code | HTTP | Category | Retryable | Message | Hint |
 |---|---|---|---|---|---|
 | <a id="bck-observability-0001"></a>`BCK.OBSERVABILITY.0001` | 500 | integration | — | Error fetching observability data from Helicone | Inspect Helicone dashboard logs for the request id in params. Common causes: invalid filter, expired token, or a transient Helicone outage. |
 | <a id="bck-observability-0002"></a>`BCK.OBSERVABILITY.0002` | 502 | integration | ✅ | Invalid response from Helicone API | Retry after a short backoff. Helicone returned a non-JSON / error-page body (usually a transient upstream incident); if it persists, check the Helicone status page. |
 | <a id="bck-observability-0003"></a>`BCK.OBSERVABILITY.0003` | 500 | integration | ❌ | Unauthorized access to Helicone API | Refresh `HELICONE_API_KEY` in the deployment env. The current key is missing, revoked, or scoped to a different workspace. |
 | <a id="bck-observability-0004"></a>`BCK.OBSERVABILITY.0004` | 429 | integration | — | Rate limit exceeded for Helicone API | Back off and retry. Helicone is rate-limiting our API key; consider increasing the plan limit or batching requests. |
 | <a id="bck-observability-0005"></a>`BCK.OBSERVABILITY.0005` | 502 | integration | — | Helicone API service unavailable | Inspect Helicone status page. The upstream Helicone API is unavailable; retry after a backoff. |
 
 ## <span id="bck-organizations"></span>`BCK.ORGANIZATIONS`
 
 | Code | HTTP | Category | Retryable | Message | Hint |
 |---|---|---|---|---|---|
 | <a id="bck-organizations-0001"></a>`BCK.ORGANIZATIONS.0001` | 500 | business | — | Error creating organization member | Inspect the underlying error in logs. Member-create failed — usually a DB-layer constraint (duplicate membership, FK violation). |
 | <a id="bck-organizations-0002"></a>`BCK.ORGANIZATIONS.0002` | 500 | business | — | Error getting organization members | Inspect the underlying error in logs. Members lookup failed — usually a DB-layer error. |
@@ -377,52 +378,52 @@
 | <a id="bck-organizations-0004"></a>`BCK.ORGANIZATIONS.0004` | 500 | business | — | Error updating organization | Inspect the underlying error in logs. Organization update failed — usually a DB-layer error or validation reject on the new fields. |
 | <a id="bck-organizations-0005"></a>`BCK.ORGANIZATIONS.0005` | 500 | business | — | Error creating organization | Inspect the underlying error in logs. Organization-create failed — usually a DB-layer error or a duplicate slug/name. |
 | <a id="bck-organizations-0006"></a>`BCK.ORGANIZATIONS.0006` | 500 | business | — | Error creating organization with first admin | The two-step bootstrap (create org + add first admin) failed. Check the underlying error in logs; the org may have been created without the admin link. |
 | <a id="bck-organizations-0007"></a>`BCK.ORGANIZATIONS.0007` | 500 | auth | — | Login failed for organization | Inspect the underlying error in logs. Org login failed — typically a misconfigured Privy app id or membership lookup error. |
 | <a id="bck-organizations-0008"></a>`BCK.ORGANIZATIONS.0008` | 403 | business | ❌ | User is already a member of the organization | The membership already exists. Read the membership instead of recreating it, or change the role via the update endpoint. |
 | <a id="bck-organizations-0009"></a>`BCK.ORGANIZATIONS.0009` | 403 | business | ❌ | User is not a member of the organization | Add the user as a member before performing membership-scoped operations. |
 | <a id="bck-organizations-0010"></a>`BCK.ORGANIZATIONS.0010` | 500 | business | — | Failed to update organization member | Inspect the underlying error in logs. Member-update failed — usually a DB-layer error. |
 | <a id="bck-organizations-0011"></a>`BCK.ORGANIZATIONS.0011` | 404 | business | ❌ | Organization not found | Verify the orgId. Soft-deleted organizations also surface as not-found. |
 | <a id="bck-organizations-0012"></a>`BCK.ORGANIZATIONS.0012` | 500 | business | — | Failed to deactivate organization | Inspect the underlying error in logs. Org deactivation failed — usually a DB-layer error. |
 | <a id="bck-organizations-0013"></a>`BCK.ORGANIZATIONS.0013` | 500 | business | — | Failed to retrieve updated organization | Inspect the underlying error in logs. The post-update re-read returned nothing — the row may have been deleted between the update and the read. |
 | <a id="bck-organizations-0014"></a>`BCK.ORGANIZATIONS.0014` | 403 | business | ❌ | User already belongs to another organization | A user can only belong to one organization at a time. Remove the user from the current organization before adding them to a new one. |
 | <a id="bck-organizations-0015"></a>`BCK.ORGANIZATIONS.0015` | 500 | integration | ✅ | Failed to look up organization (database error) | Repository.findOne returned a driver/connection error rather than null. Inspect the cause field on the server log; if the database is up, this is likely a query timeout or connection-pool exhaustion. Distinct from BCK.ORGANIZATIONS.0011, which signals a confirmed not-found result. |
 | <a id="bck-organizations-0016"></a>`BCK.ORGANIZATIONS.0016` | 404 | business | ❌ | Organization customer not found | Verify the customerId is correct and belongs to the organization in the URL. Customers are scoped per-org; a customer that exists in another org will surface as not-found here. |
 | <a id="bck-organizations-0017"></a>`BCK.ORGANIZATIONS.0017` | 422 | business | ❌ | Cannot remove the last admin from the organization | An organization must always have at least one active admin. Promote another member to Admin (or invite a new one) before demoting, deactivating, or removing the last admin. |
 | <a id="bck-organizations-0018"></a>`BCK.ORGANIZATIONS.0018` | 404 | business | ❌ | Organization member not found | Verify the memberId (the OrganizationMember row PK) and that it belongs to the orgId in the URL. Deactivated members still exist; truly removed members return 404. |
 | <a id="bck-organizations-0019"></a>`BCK.ORGANIZATIONS.0019` | 403 | business | ❌ | Customer management is not available for this organization tier | Viewing organization customers requires the Enterprise tier. Upgrade the organization to Enterprise to access the customers tab and per-customer activity. (Customers are still tracked on every tier — only the view is gated.) |
 | <a id="bck-organizations-0020"></a>`BCK.ORGANIZATIONS.0020` | 403 | business | ❌ | Activity feed is not available for this organization tier | The activity feed is a Premium+ feature. Upgrade the organization to Premium or Enterprise to access the activity log. |
 | <a id="bck-organizations-0021"></a>`BCK.ORGANIZATIONS.0021` | 403 | business | ❌ | Outbound webhooks are not available for this organization tier | Outbound webhooks are a Premium+ feature. Upgrade the organization to Premium or Enterprise to subscribe to org events from external systems. |
 | <a id="bck-organizations-0022"></a>`BCK.ORGANIZATIONS.0022` | 403 | business | ❌ | Analytics are not available for this organization tier | The analytics dashboard is a Premium+ feature. Upgrade the organization to Premium or Enterprise to access revenue, customer, and agent-usage metrics. |
 | <a id="bck-organizations-0023"></a>`BCK.ORGANIZATIONS.0023` | 404 | business | ❌ | Webhook subscription not found | Verify the subscription id and that it belongs to the orgId in the URL. Deleted subscriptions return 404. |
 | <a id="bck-organizations-0024"></a>`BCK.ORGANIZATIONS.0024` | 422 | validation | ❌ | Invalid webhook URL: must be a valid URL with http or https scheme | Provide an absolute URL with an http:// or https:// scheme. Schemes like ftp:// or relative URLs are rejected. |
 | <a id="bck-organizations-0025"></a>`BCK.ORGANIZATIONS.0025` | 422 | validation | ❌ | Webhook URL must use HTTPS in production environments | Webhook URLs in live environments must use HTTPS so the signed payload cannot be intercepted in transit. Use HTTPS, or test against the sandbox environment which permits HTTP for local development. |
 | <a id="bck-organizations-0026"></a>`BCK.ORGANIZATIONS.0026` | 404 | business | ❌ | Webhook delivery not found | Verify the deliveryId. Old deliveries may be pruned by the retention job; check the activity feed for the parent event instead. |
 | <a id="bck-organizations-0027"></a>`BCK.ORGANIZATIONS.0027` | 404 | business | ❌ | Webhook delivery not found in this organization | The delivery exists but belongs to a different organization. Use the orgId that owns the delivery, or call this endpoint as a member of that org. |
 | <a id="bck-organizations-0028"></a>`BCK.ORGANIZATIONS.0028` | 404 | business | ❌ | User organisation info not found | The user exists but has no membership matching the requested environment. Verify the userId and environment query param. |
 | <a id="bck-organizations-0029"></a>`BCK.ORGANIZATIONS.0029` | 400 | validation | ❌ | Role transition not permitted: only Admin and Member roles are assignable | Pass role=Admin or role=Member. Other role values (Owner, Client, etc.) are not supported via this endpoint. |
 | <a id="bck-organizations-0030"></a>`BCK.ORGANIZATIONS.0030` | 400 | auth | ❌ | Required caller identity is missing from the request | The userId/address fields populated by the auth guards were absent. This typically means the guard chain has been misconfigured — the endpoint should be reachable only after auth. |
 | <a id="bck-organizations-0031"></a>`BCK.ORGANIZATIONS.0031` | 403 | business | ❌ | Realtime event streaming is not available for this organization tier | The realtime (WebSocket) activity stream is an Enterprise-only feature. Upgrade the organization to Enterprise to manage WebSocket secrets and subscribe to the live event stream. |
 | <a id="bck-organizations-0032"></a>`BCK.ORGANIZATIONS.0032` | 404 | business | ❌ | WebSocket secret not found | No WebSocket secret with that id exists for the current member in this organization. It may have already been deleted, or belongs to a different member. |
 | <a id="bck-organizations-0033"></a>`BCK.ORGANIZATIONS.0033` | 500 | business | ✅ | Failed to onboard customer | White-label customer provisioning failed unexpectedly (e.g. a Privy or key-minting outage). Inspect the underlying error in logs and retry — provisioning is idempotent by email. |
-| <a id="bck-organizations-0034"></a>`BCK.ORGANIZATIONS.0034` | 409 | business | ❌ | This customer is blocked by your organization | Your organization has blocked this customer, so no new credential can be issued to them. Unblock them first (POST /organizations/{orgId}/customers/{customerId}/unblock) if this was in error. |
+| <a id="bck-organizations-0034"></a>`BCK.ORGANIZATIONS.0034` | 409 | business | ❌ | This customer is blocked by your organization | Your organization has blocked this customer, so no new credential can be issued to them. Unblock them first (POST /organizations/&#123;orgId&#125;/customers/&#123;customerId&#125;/unblock) if this was in error. |
 | <a id="bck-organizations-0035"></a>`BCK.ORGANIZATIONS.0035` | 409 | business | ❌ | This account has been disabled | The Nevermined account behind this email is disabled, so no credential can be issued for it. Contact support if the account should be reactivated. |
 | <a id="bck-organizations-0036"></a>`BCK.ORGANIZATIONS.0036` | 500 | business | ✅ | Could not securely complete the member invitation | The bootstrap key minted while provisioning the invitee could not be revoked, so the invitation was failed closed rather than leave a live credential on the invitee account. Inspect the underlying error in logs and retry — provisioning is idempotent by email. |
 
 ## <span id="bck-org_integration"></span>`BCK.ORG_INTEGRATION`
 
 | Code | HTTP | Category | Retryable | Message | Hint |
 |---|---|---|---|---|---|
 | <a id="bck-org_integration-0001"></a>`BCK.ORG_INTEGRATION.0001` | 404 | business | ❌ | Organization not found or not eligible for agentic integration | The org id either does not exist, is inactive, or does not have an active paid subscription. Only Premium and Enterprise orgs expose agentic integration files. |
 | <a id="bck-org_integration-0002"></a>`BCK.ORG_INTEGRATION.0002` | 500 | internal | ✅ | Failed to render organization integration document | Inspect the underlying error in logs. The integration template rendering failed — usually a missing template variable or a malformed organization metadata row. |
 
 ## <span id="bck-org_wallets"></span>`BCK.ORG_WALLETS`
 
 | Code | HTTP | Category | Retryable | Message | Hint |
 |---|---|---|---|---|---|
 | <a id="bck-org_wallets-0001"></a>`BCK.ORG_WALLETS.0001` | 422 | business | ❌ | Organization wallet cap reached: cannot create more wallets for this organization | The organization-wallet cap for this tier has been reached. Premium allows one; upgrade to Enterprise for more. |
 | <a id="bck-org_wallets-0002"></a>`BCK.ORG_WALLETS.0002` | 404 | business | ❌ | Organization wallet not found | No organization wallet with this id exists for the specified organization. |
 | <a id="bck-org_wallets-0003"></a>`BCK.ORG_WALLETS.0003` | 502 | integration | ✅ | Failed to provision the organization wallet | The custodial wallet provider could not create the wallet. Retry; if it persists, contact support. |
 | <a id="bck-org_wallets-0004"></a>`BCK.ORG_WALLETS.0004` | 403 | business | ❌ | Organization wallets are not available on this tier | Organization stablecoin wallets require a Premium or Enterprise organization. |
 | <a id="bck-org_wallets-0005"></a>`BCK.ORG_WALLETS.0005` | 409 | business | ❌ | Wallet is already shared with this group | This organization wallet already funds the group; nothing to add. |
 | <a id="bck-org_wallets-0006"></a>`BCK.ORG_WALLETS.0006` | 404 | business | ❌ | Wallet is not shared with this group | This organization wallet does not fund the specified group; nothing to remove. |
 | <a id="bck-org_wallets-0007"></a>`BCK.ORG_WALLETS.0007` | 502 | integration | ❌ | Failed to withdraw from the organization wallet | The withdrawal may have partially completed. Check the wallet’s balance and recent transactions before retrying; contact support if unsure. |
@@ -432,42 +433,42 @@
 
 ## <span id="bck-payment_credential"></span>`BCK.PAYMENT_CREDENTIAL`
 
 | Code | HTTP | Category | Retryable | Message | Hint |
 |---|---|---|---|---|---|
 | <a id="bck-payment_credential-0001"></a>`BCK.PAYMENT_CREDENTIAL.0001` | 500 | internal | ❌ | Canonical payment-credential dual-write failed (mirror drift) | Epic #1958 T1.A: the canonical payment_credentials/payment_instruments mirror could not be kept in sync with payment_methods (enrol/revoke/webhook fan-out). The legacy payment_methods write already succeeded — this is logged-and-swallowed because the mirror is non-authoritative while PAYMENT_CREDENTIALS_ENABLED is the only consumer. Alert on this code: drift must be reconciled before the canonical model becomes load-bearing (T1.B/T1.C). Inspect the logged stack for the underlying DB error. |
 | <a id="bck-payment_credential-0002"></a>`BCK.PAYMENT_CREDENTIAL.0002` | 500 | internal | ❌ | Canonical payment-credential resolve failed (delegation FK) | Epic #1958 T1.B: resolving the delegation→payment_credentials FK at delegation-create time failed (resolveActiveCredentialId). Logged-and-swallowed — the delegation is created with credentialId NULL, identical to the flag-off path, because the FK is a non-authoritative back-reference while PAYMENT_CREDENTIALS_ENABLED is the only consumer. Distinct from 0001 (dual-write/mirror) so an alert can tell a resolve-during-create failure from an enrol/revoke/webhook mirror failure. Inspect the logged stack for the underlying DB error. |
 | <a id="bck-payment_credential-0003"></a>`BCK.PAYMENT_CREDENTIAL.0003` | 500 | internal | ❌ | Canonical payment-credential instrument lookup failed (charge router) | Epic #1958 T1.C: loading a credential’s active payment_instruments for the charge-time router (listActiveInstrumentsForCredential) failed. Logged-and-swallowed — the router falls back to the retained delegations.provider column, identical to the flag-off path, because the derivation is non-authoritative while PAYMENT_CREDENTIALS_ENABLED is the only consumer. Distinct from 0001 (dual-write/mirror) and 0002 (resolve-on-create) so an alert can pinpoint a derive-at-charge failure. Inspect the logged stack for the underlying DB error. |
 | <a id="bck-payment_credential-0004"></a>`BCK.PAYMENT_CREDENTIAL.0004` | 404 | business | ❌ | Unified card enrolment is not available | Epic #1958 T3.A: the unified VGS-Collect card-enrol endpoint (POST /api/v1/delegation/enroll) is gated behind the PAYMENT_CREDENTIALS_ENABLED flag and is OFF in this environment. The legacy enrol paths (enroll-card / enroll-braintree / enroll-visa) remain available. 404 (not 503) so a flag-off deploy presents the endpoint as simply absent. |
 
 ## <span id="bck-paypal"></span>`BCK.PAYPAL`
 
 | Code | HTTP | Category | Retryable | Message | Hint |
 |---|---|---|---|---|---|
 | <a id="bck-paypal-0001"></a>`BCK.PAYPAL.0001` | 500 | integration | — | Unexpected error during PayPal/Braintree checkout | Inspect the underlying error in logs. PayPal-via-Braintree checkout failed — usually a Braintree transaction reject or PayPal account restriction. |
 
 ## <span id="bck-plans"></span>`BCK.PLANS`
 
 | Code | HTTP | Category | Retryable | Message | Hint |
 |---|---|---|---|---|---|
 | <a id="bck-plans-0001"></a>`BCK.PLANS.0001` | 500 | internal | ❌ | Plan lookup failed: plan with the given entryId not found in service layer | The service-layer findOneById returned null. Original behaviour was a generic 500; consumer code that needs 404 semantics should use BCK.PROTOCOL.0003. |
 
 ## <span id="bck-point"></span>`BCK.POINT`
 
 | Code | HTTP | Category | Retryable | Message | Hint |
 |---|---|---|---|---|---|
 | <a id="bck-point-0001"></a>`BCK.POINT.0001` | 403 | business | ❌ | User with address is not allowed to access | Register the caller wallet as a user before accruing points. The points endpoints require a user-profile row; re-authenticating the same wallet will not grant access. |
 | <a id="bck-point-0002"></a>`BCK.POINT.0002` | 404 | business | — | User with id not found | Verify the user id. The user may have been deleted or never existed. |
 | <a id="bck-point-0003"></a>`BCK.POINT.0003` | 404 | business | — | Unable to search user points | Verify the user id and that points retention has not pruned the rows. Empty per-user point lookups surface as 404. |
 | <a id="bck-point-0004"></a>`BCK.POINT.0004` | 404 | business | — | Unable to search event points | Verify the event id. Empty per-event point lookups surface as 404. |
 | <a id="bck-point-0005"></a>`BCK.POINT.0005` | 404 | business | — | Unable to find user points aggregated | Verify the user id. Empty aggregated lookups surface as 404. |
 | <a id="bck-point-0006"></a>`BCK.POINT.0006` | 404 | business | — | Points rule not found | Verify the ruleId. Empty rule lookups surface as 404; rules may be disabled or removed. |
 | <a id="bck-point-0007"></a>`BCK.POINT.0007` | 403 | business | ❌ | Points rule recurrency exhausted for user | The rule allows only one (or N) accruals per user; the cap has been reached. |
 | <a id="bck-point-0008"></a>`BCK.POINT.0008` | 500 | internal | — | Points rule recurrency type not implemented | The rule references an unimplemented recurrency type. Update points.rules.ts to use one of: onlyonce, timeslimitted, onceperitem, capday, capweek, capmonth. |
 | <a id="bck-point-0009"></a>`BCK.POINT.0009` | 500 | internal | ❌ | No points rule matches the supplied price/role | The price/role tiers in points.rules.ts are exhaustive for non-negative inputs; reaching this code typically means a negative or otherwise unexpected price was supplied. The status is 500 to preserve the original "throw new Error" behaviour from before #1538; a follow-up (tracked in the Wave-B issue) will demote this to 400 and add input validation at the API boundary. |
 | <a id="bck-point-0010"></a>`BCK.POINT.0010` | 403 | business | ❌ | Unsupported points cap recurrency type | The rule references a cap recurrency variant that the engine does not recognise. Update the rule to one of capday/capweek/capmonth. |
 | <a id="bck-point-0011"></a>`BCK.POINT.0011` | 403 | business | ❌ | Points rule (onlyonce) already accrued by this user | The rule allows exactly one accrual per user and the user already received their share. No retry will succeed. |
 | <a id="bck-point-0012"></a>`BCK.POINT.0012` | 403 | business | ❌ | Points rule (timeslimitted) per-user lifetime cap reached | The rule allows at most rule.cap accruals per (user, rule); the user has reached that ceiling and the cap does not reset. Note: the throw-site `details` line may mention an item reference for historical reasons — the check is per-user, not per-item. Per-item semantics live in BCK.POINT.0013 (onceperitem). |
 | <a id="bck-point-0013"></a>`BCK.POINT.0013` | 403 | business | ❌ | Points rule (onceperitem) already accrued for this item | The user already received points for this specific item/reference. Try a different item. |
 | <a id="bck-point-0014"></a>`BCK.POINT.0014` | 403 | business | ❌ | Points rule (capday/week/month) time-window cap exhausted | The user reached the cap for this rule within the current time window (day/week/month). Wait for the window to roll over. |
 | <a id="bck-point-0015"></a>`BCK.POINT.0015` | 500 | internal | ❌ | No subscription-price points rule for the supplied price | getRuleIdBySubscriptionPrice() saw a price the tier table does not cover — typically a negative value. Add input validation at the API boundary. |
 | <a id="bck-point-0016"></a>`BCK.POINT.0016` | 500 | internal | ❌ | No crypto-seller points rule for the supplied price | getRuleIdByCryptoSellerPrice() saw a price the tier table does not cover. |
@@ -477,15 +478,15 @@
 
 ## <span id="bck-protocol"></span>`BCK.PROTOCOL`
 
 | Code | HTTP | Category | Retryable | Message | Hint |
 |---|---|---|---|---|---|
 | <a id="bck-protocol-0001"></a>`BCK.PROTOCOL.0001` | 500 | integration | — | Unable to register payment plan | Inspect the underlying error in logs. Payment-plan registration failed at protocol or SDK layer — usually a chain revert or missing token approval. |
 | <a id="bck-protocol-0002"></a>`BCK.PROTOCOL.0002` | 500 | integration | — | Unable to register agent | Inspect the underlying error in logs. Agent registration failed at protocol or SDK layer — usually a chain revert or duplicate agentId. |
 | <a id="bck-protocol-0003"></a>`BCK.PROTOCOL.0003` | 404 | integration | — | Unable to get payment plan by planId | Verify the planId. The plan may have been removed at the protocol side or never registered. Sandbox/live mismatches surface here too. |
 | <a id="bck-protocol-0004"></a>`BCK.PROTOCOL.0004` | 404 | integration | — | Unable to get agent by agentId | Verify the agentId. The agent may have been removed at the protocol side or never registered. Sandbox/live mismatches surface here too. |
 | <a id="bck-protocol-0005"></a>`BCK.PROTOCOL.0005` | 500 | integration | — | Error ordering plan | Inspect the underlying error in logs. Plan ordering failed — usually insufficient balance, expired plan, or chain revert. |
 | <a id="bck-protocol-0006"></a>`BCK.PROTOCOL.0006` | 500 | integration | — | Error getting balance of plan | Inspect the underlying error in logs. Balance retrieval reverted — verify the planId and that the chain RPC is reachable. |
 | <a id="bck-protocol-0007"></a>`BCK.PROTOCOL.0007` | 500 | integration | — | Error minting plan | Inspect the underlying error in logs. Credit minting reverted — verify the planId, credit type, and the minter role on the protocol contract. |
 | <a id="bck-protocol-0008"></a>`BCK.PROTOCOL.0008` | 500 | integration | — | Error deleting plan from agent | Inspect the underlying error in logs. The agent→plan unlink call reverted — verify the caller owns both the agent and the plan. |
 | <a id="bck-protocol-0009"></a>`BCK.PROTOCOL.0009` | 500 | integration | — | Error adding plan to agent | Inspect the underlying error in logs. The agent→plan link call reverted — verify the caller owns both the agent and the plan. |
 | <a id="bck-protocol-0010"></a>`BCK.PROTOCOL.0010` | 403 | integration | — | Invalid credits type | Provide one of the valid credit types: FIXED, DYNAMIC, EXPIRABLE. Other strings are rejected by the protocol layer. |
@@ -494,145 +495,146 @@
 | <a id="bck-protocol-0013"></a>`BCK.PROTOCOL.0013` | 500 | integration | — | Error updating plan | Inspect the underlying error in logs. Plan metadata update reverted — verify the caller owns the plan and the new metadata is well-formed. |
 | <a id="bck-protocol-0014"></a>`BCK.PROTOCOL.0014` | 500 | integration | — | Error de-activating agent | Inspect the underlying error in logs. Agent de-activation reverted — verify the caller owns the agent and it is not already inactive. |
 | <a id="bck-protocol-0015"></a>`BCK.PROTOCOL.0015` | 500 | integration | — | Error de-activating plan | Inspect the underlying error in logs. Plan de-activation reverted — verify the caller owns the plan and it is not already inactive. |
 | <a id="bck-protocol-0016"></a>`BCK.PROTOCOL.0016` | 403 | business | ❌ | The user doesnt own this agent | Only the wallet that registered the agent can perform owner-scoped operations. Re-authenticating as the same caller will not help. |
 | <a id="bck-protocol-0017"></a>`BCK.PROTOCOL.0017` | 403 | business | ❌ | The user doesnt own this plan | Only the wallet that registered the plan can perform owner-scoped operations. Re-authenticating as the same caller will not help. |
 | <a id="bck-protocol-0018"></a>`BCK.PROTOCOL.0018` | 200 | integration | — | The agent is already in the desired state | No action required. The agent is already in the requested active/inactive state; the response carries the current state in params. |
 | <a id="bck-protocol-0019"></a>`BCK.PROTOCOL.0019` | 200 | integration | — | The plan is already in the desired state | No action required. The plan is already in the requested active/inactive state; the response carries the current state in params. |
 | <a id="bck-protocol-0020"></a>`BCK.PROTOCOL.0020` | 500 | integration | — | Error redeming credits | Inspect the underlying error in logs. Credit redemption reverted — verify the buyer holds enough credits and the plan permits redemption at this point. |
 | <a id="bck-protocol-0021"></a>`BCK.PROTOCOL.0021` | 500 | integration | — | Error getting user plans | Inspect the underlying error in logs. The per-user plans query failed — usually a DB-layer or chain-RPC issue. |
 | <a id="bck-protocol-0022"></a>`BCK.PROTOCOL.0022` | 404 | integration | — | Error getting user agents | Verify the user address. Empty per-user agent listings surface as 404; users with zero agents fall through this code. |
 | <a id="bck-protocol-0023"></a>`BCK.PROTOCOL.0023` | 404 | integration | — | Error getting plan associated to agent. Agent not found | Verify the agentId. The agent may have been removed, or no plan is associated with it yet. |
 | <a id="bck-protocol-0024"></a>`BCK.PROTOCOL.0024` | 404 | integration | — | Error getting agent associated to plan. Plan not found | Verify the planId. The plan may have been removed, or no agent is associated with it yet. |
 | <a id="bck-protocol-0025"></a>`BCK.PROTOCOL.0025` | 500 | integration | — | Unable to generate agent access token | Inspect the underlying error in logs. Agent access-token minting failed — verify the agent is registered and the requesting plan is active. |
 | <a id="bck-protocol-0026"></a>`BCK.PROTOCOL.0026` | 403 | integration | — | The agent doesnt include the plan specified | Re-link the plan to the agent (or use a different plan that is linked to this agent). Plans without an explicit link cannot grant access. |
 | <a id="bck-protocol-0027"></a>`BCK.PROTOCOL.0027` | 403 | integration | — | Unable to validate access token | Re-mint the access token. The supplied token is expired, malformed, or signed by a key the API does not recognise. |
 | <a id="bck-protocol-0028"></a>`BCK.PROTOCOL.0028` | 403 | integration | — | Invalid agent ID in access token | Verify the agentId encoded in the access-token claim matches the agent the caller is invoking. Cross-agent token use is rejected. |
 | <a id="bck-protocol-0029"></a>`BCK.PROTOCOL.0029` | 403 | integration | — | Proof is required for this plan | Attach a signed proof to the request when ordering against this plan. The plan owner enabled proof-required for credit redemption. |
 | <a id="bck-protocol-0030"></a>`BCK.PROTOCOL.0030` | 403 | integration | — | Invalid proof | Re-sign the proof. The proof signature does not validate against the registered signer or the proof payload does not match the request. |
 | <a id="bck-protocol-0031"></a>`BCK.PROTOCOL.0031` | 403 | integration | — | Endpoint not included in the agent api | Add the endpoint to the agent metadata `endpoints` array (or call a registered endpoint). Only listed endpoints are reachable via the access token. |
 | <a id="bck-protocol-0032"></a>`BCK.PROTOCOL.0032` | 500 | integration | — | Unable to track access transaction | Inspect the underlying error in logs. The access-tx insert failed — usually a DB-layer or queue-layer error. Metrics are best-effort; the consumer request still completed. |
 | <a id="bck-protocol-0033"></a>`BCK.PROTOCOL.0033` | 403 | integration | — | You do not have permission to track access transactions for this owner | Authenticate as the agent or plan owner before retrying. Only owners can track access transactions for resources they own. |
 | <a id="bck-protocol-0034"></a>`BCK.PROTOCOL.0034` | 500 | integration | — | Unable to track access processor queue entry | Inspect the underlying error in logs. The processor-queue insert failed — usually a queue-layer error. Safe to retry idempotently. |
 | <a id="bck-protocol-0035"></a>`BCK.PROTOCOL.0035` | 500 | integration | — | Unable to track agent task | Inspect the underlying error in logs. The agent-task tracking insert failed — usually a DB-layer or constraint issue. |
 | <a id="bck-protocol-0036"></a>`BCK.PROTOCOL.0036` | 500 | integration | — | Unable to track agent processor queue entry | Inspect the underlying error in logs. The agent-task processor-queue insert failed — usually a queue-layer error. Safe to retry idempotently. |
 | <a id="bck-protocol-0037"></a>`BCK.PROTOCOL.0037` | 404 | integration | — | Agent task not found | Verify the taskId and that it belongs to the caller agent. Task ids are scoped per-agent. |
 | <a id="bck-protocol-0038"></a>`BCK.PROTOCOL.0038` | 500 | integration | — | Error updating agent task | Inspect the underlying error in logs. Agent-task update failed — usually a state-transition guard rejection (the task is in a terminal state). |
 | <a id="bck-protocol-0039"></a>`BCK.PROTOCOL.0039` | 500 | integration | — | Error redeeming credits and updating agent task | Inspect the underlying error in logs. The combined redeem+update transaction failed mid-way — the DB row may be left inconsistent and need manual reconciliation. |
 | <a id="bck-protocol-0040"></a>`BCK.PROTOCOL.0040` | 500 | integration | — | Unable to register agent and plan | Inspect the underlying error in logs. The combined register-agent-and-plan call failed — verify the caller owns both resources and the protocol contract is reachable. |
 | <a id="bck-protocol-0041"></a>`BCK.PROTOCOL.0041` | 403 | integration | — | The user doesnt have a valid Stripe account enabled | Complete Stripe Connect onboarding before publishing fiat plans. Until charges_enabled is true on the Connect account, plans cannot be sold for fiat. |
 | <a id="bck-protocol-0042"></a>`BCK.PROTOCOL.0042` | 403 | integration | — | Either amount or marginPercent must be provided, but not both | Send exactly one of amount or marginPercent on a DYNAMIC plan. The two fields are mutually exclusive — pick the pricing model that fits. |
 | <a id="bck-protocol-0043"></a>`BCK.PROTOCOL.0043` | 403 | integration | — | Plan does not have valid price configuration for margin calculation. Credits type must be DYNAMIC. | Re-publish the plan with credits.type=DYNAMIC and the required margin/cost configuration. Margin calculations are only valid for DYNAMIC plans. |
 | <a id="bck-protocol-0044"></a>`BCK.PROTOCOL.0044` | 404 | integration | — | No Helicone request found for agent request ID | Verify the Helicone request id and that the agent invocation actually fired through the Helicone proxy. Stale ids and proxied-off agents land here. |
 | <a id="bck-protocol-0045"></a>`BCK.PROTOCOL.0045` | 500 | integration | — | Error getting all plans | Inspect the underlying error in logs. The list-all-plans query failed — usually a DB-layer error or pagination issue. |
 | <a id="bck-protocol-0046"></a>`BCK.PROTOCOL.0046` | 400 | integration | — | Fiat plan price exceeds the maximum allowed ($999,999.99). Stripe does not support payment intents above this limit. | Lower the plan price below $999,999.99 (Stripe payment-intent cap). Higher-value sales must go through Stripe Connect transfers or off-platform settlement. |
 | <a id="bck-protocol-0047"></a>`BCK.PROTOCOL.0047` | 400 | integration | — | Fiat plan price is below the minimum allowed ($1.00). Lower prices do not cover the payment-processor fixed fee. | Raise the plan price to at least $1.00. Lower prices do not cover the payment-processor fixed fee and would settle at a loss. |
 | <a id="bck-protocol-0048"></a>`BCK.PROTOCOL.0048` | 400 | business | — | Plan and agent must belong to the same organization. A Personal plan cannot be linked to an organization agent (and vice versa); plans owned by one organization cannot be linked to agents owned by a different organization. | Either move the plan or the agent so both belong to the same organization (or both to the same Personal account). Cross-org and personal-vs-org links are rejected by design. |
 | <a id="bck-protocol-0049"></a>`BCK.PROTOCOL.0049` | 500 | integration | ❌ | On-chain submit returned without a transaction hash | The chain broadcast call succeeded at the SDK boundary but did not return a tx hash. Treat as an SDK-shape drift; the dead-letter accounting flags the row so it can be re-tried after investigation. |
 | <a id="bck-protocol-0050"></a>`BCK.PROTOCOL.0050` | 400 | business | ❌ | Fiat plans cannot be ordered through this endpoint. Use the x402 card-delegation settle flow (POST /api/v1/x402/settle) so the buyer card delegation can be charged before credits are provisioned. | This endpoint settles stablecoin (crypto) plans only. For fiat / `nvm:card-delegation` plans, register a card delegation and call /api/v1/x402/settle — that path charges the card BEFORE credits are provisioned in the off-chain ledger. On-chain mirroring (when the plan opts in) happens asynchronously after settlement; do not assume synchronous on-chain finality. |
 | <a id="bck-protocol-0051"></a>`BCK.PROTOCOL.0051` | 503 | integration | ✅ | Chain RPC dependency temporarily unavailable | A transient failure of the on-chain RPC provider / bundler prevented the write from completing (e.g. the provider returned 5xx or was unreachable). Retry after a short backoff. If it persists, the RPC endpoint or its credentials may be misconfigured. |
 | <a id="bck-protocol-0052"></a>`BCK.PROTOCOL.0052` | 400 | validation | ❌ | Unsupported settlement network | The requested network (chainId) is not served by this environment. Use a supported network — sandbox serves Base Sepolia (84532) and Tempo Moderato (42431); live serves Base (8453) and Tempo (4217). Off-chain plans (org-tier) do not settle on a chain (#1929). |
 | <a id="bck-protocol-0053"></a>`BCK.PROTOCOL.0053` | 400 | validation | ❌ | Plan and agent must settle on the same network | A plan can only be linked to an agent on the same settlement network (chainId). A Tempo plan cannot be linked to a Base agent (and vice versa). Register the plan and agent on the same network, or link a plan that already settles on the agent’s network (#1929). |
 | <a id="bck-protocol-0054"></a>`BCK.PROTOCOL.0054` | 503 | integration | ❌ | Could not migrate the agent ownership to your current wallet | Your agent was registered by a wallet that has since been migrated, and handing it over to your current wallet failed on-chain (bundler/paymaster/RPC), or a recent attempt is in its cooldown window. Do NOT retry in a loop — wait a few minutes and try the operation again. See #2152. |
-| <a id="bck-protocol-0055"></a>`BCK.PROTOCOL.0055` | 404 | validation | ❌ | Payment plan does not exist on-chain | The request references a planId that is not registered on the settlement network, so the on-chain call reverted with PlanNotFound. Check the planId (it is a uint256 decimal string, not a DID) and that it was created on the SAME network you are writing to. GET /api/v1/protocol/plans/{planId} confirms whether it exists (#2163). |
+| <a id="bck-protocol-0055"></a>`BCK.PROTOCOL.0055` | 404 | validation | ❌ | Payment plan does not exist on-chain | The request references a planId that is not registered on the settlement network, so the on-chain call reverted with PlanNotFound. Check the planId (it is a uint256 decimal string, not a DID) and that it was created on the SAME network you are writing to. GET /api/v1/protocol/plans/&#123;planId&#125; confirms whether it exists (#2163). |
 | <a id="bck-protocol-0056"></a>`BCK.PROTOCOL.0056` | 409 | business | ❌ | This plan can only be purchased once per account, and you already own it | The plan installs the one-time-purchase hook (OneTimeCreatorHook), which allows a single agreement per (plan, buyer). Your account has already ordered it, so the on-chain call reverted with CreatorAlreadyCreatedAgreement. Nothing was charged. Use the credits you already hold, or order a different plan (#2164). |
 | <a id="bck-protocol-0057"></a>`BCK.PROTOCOL.0057` | 400 | validation | ❌ | A value in the request could not be encoded for the on-chain call | An address or numeric value in the payload is malformed, so the call could not even be encoded — most commonly a token/receiver address whose EIP-55 checksum is wrong (mixed-case addresses are checksum-verified). Send the address all-lowercase, or with a correct checksum. `params.detail` names the offending value (#2478). |
 
 ## <span id="bck-router"></span>`BCK.ROUTER`
 
 | Code | HTTP | Category | Retryable | Message | Hint |
 |---|---|---|---|---|---|
 | <a id="bck-router-0001"></a>`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`. The per-failure `details` names the specific problem. |
 | <a id="bck-router-0002"></a>`BCK.ROUTER.0002` | 409 | business | ❌ | requestId already used | This `requestId` already minted a credential (idempotency). Omit it or use a fresh value — one credential per requestId. |
 | <a id="bck-router-0003"></a>`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. Create or top up a delegation via POST /api/v1/delegation/create. |
 | <a id="bck-router-0004"></a>`BCK.ROUTER.0004` | 404 | business | ❌ | Router payment not found | No Router payment with that id belongs to the authenticated user. |
 | <a id="bck-router-0005"></a>`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. |
 | <a id="bck-router-0006"></a>`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. |
 | <a id="bck-router-0007"></a>`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. Let some complete before starting more, or slow the request rate. |
 | <a id="bck-router-0008"></a>`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 will be issued as v2 (EIP-7702) and works with the Router. Existing v1 keys keep working for credit-based (nvm:erc4337) flows until they expire. |
 | <a id="bck-router-0009"></a>`BCK.ROUTER.0009` | 402 | business | ❌ | Insufficient wallet balance to fund the payment | The buyer's custodial wallet does not hold enough of the payment asset on the target network to cover this charge. This is distinct from the delegation cap (BCK.ROUTER.0003): the cap authorizes the spend, but the wallet must also actually hold the funds. Fund the wallet on the target chain and retry. (MPP-tempo / crypto pulls settle from the wallet's own balance; the router never holds funds.) |
+| <a id="bck-router-0010"></a>`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 (#2191) 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. |
 
 ## <span id="bck-stripe"></span>`BCK.STRIPE`
 
 | Code | HTTP | Category | Retryable | Message | Hint |
 |---|---|---|---|---|---|
 | <a id="bck-stripe-0001"></a>`BCK.STRIPE.0001` | 400 | integration | — | Error creating Stripe account | Inspect Stripe dashboard logs for the request id we return in params. Account creation failed at the Stripe side — usually a missing legal entity or invalid country. |
 | <a id="bck-stripe-0002"></a>`BCK.STRIPE.0002` | 400 | integration | — | Error creating Stripe checkout session | Inspect Stripe dashboard logs for the request id we return in params. Checkout session creation failed — verify the plan’s priceId is live and the Connect account is fully onboarded. |
 | <a id="bck-stripe-0003"></a>`BCK.STRIPE.0003` | 400 | integration | — | Error creating Stripe payment intent | Inspect Stripe dashboard logs for the request id we return in params. PaymentIntent creation failed — usually an invalid currency/amount or missing customer. |
 | <a id="bck-stripe-0004"></a>`BCK.STRIPE.0004` | 400 | integration | — | Error processing Stripe account webhook for updating an account | Inspect the underlying error and the Stripe event id in params. The webhook handler failed; the event will be retried by Stripe. |
 | <a id="bck-stripe-0005"></a>`BCK.STRIPE.0005` | 400 | integration | — | Error processing Stripe connect webhook | Inspect the underlying error and Stripe event id in params. The Connect webhook handler rejected the payload — usually a schema mismatch or unsupported event type. |
 | <a id="bck-stripe-0006"></a>`BCK.STRIPE.0006` | 500 | integration | — | Error processing Stripe checkout event with error | Inspect the underlying error and Stripe event id in params. The checkout-completed handler failed; manual reconciliation may be needed for the buyer. |
 | <a id="bck-stripe-0007"></a>`BCK.STRIPE.0007` | 400 | integration | — | Invalid input params | Verify the request body matches the endpoint schema. Common cause: missing planId or zero amount. |
 | <a id="bck-stripe-0008"></a>`BCK.STRIPE.0008` | 400 | integration | — | Stripe event not handled | Stripe sent an event type this deployment does not handle. Safe to ignore unless the event is one we expect to act on — in which case add the handler. |
 | <a id="bck-stripe-0009"></a>`BCK.STRIPE.0009` | 400 | integration | — | The plan indicated is not valid for Stripe payment | Verify the planId references a fiat plan with a configured Stripe priceId. Crypto-only plans cannot be paid via Stripe. |
 | <a id="bck-stripe-0010"></a>`BCK.STRIPE.0010` | 400 | integration | — | The plan is not a Fiat plan | Use a fiat plan for Stripe checkout. Crypto plans must be paid through the on-chain flow (/protocol/order or x402). |
 | <a id="bck-stripe-0011"></a>`BCK.STRIPE.0011` | 400 | integration | — | Error calculating plan checkout price | Inspect the underlying error and the planId in params. Checkout-price computation failed — usually a missing/invalid price metadata or platform-fee config. |
 | <a id="bck-stripe-0012"></a>`BCK.STRIPE.0012` | 400 | integration | — | The account selling the plan is not properly configured to accept Stripe payments | The plan seller must complete Stripe Connect onboarding (charges_enabled + payouts_enabled). Until then their plans cannot be sold via Stripe. |
 | <a id="bck-stripe-0013"></a>`BCK.STRIPE.0013` | 400 | integration | — | Payment intent not succeeded | The Stripe PaymentIntent is not in a terminal success state. Check status in the Stripe dashboard; if it is processing, retry after the webhook lands. |
 | <a id="bck-stripe-0014"></a>`BCK.STRIPE.0014` | 400 | integration | — | Invalid payment amount from payment intent | The PaymentIntent amount does not match the expected plan price. Verify currency and amount on the Stripe side; mismatched currencies are the most common cause. |
 | <a id="bck-stripe-0015"></a>`BCK.STRIPE.0015` | 400 | integration | — | Customer not found | Verify the Stripe customerId. The customer may have been deleted in the Stripe dashboard or never created for this user. |
 | <a id="bck-stripe-0016"></a>`BCK.STRIPE.0016` | 400 | integration | — | Subscription not found | Verify the Stripe subscriptionId. The subscription may have been canceled and pruned, or belong to a different account/environment. |
 | <a id="bck-stripe-0017"></a>`BCK.STRIPE.0017` | 400 | integration | — | Invoices not found | Verify the Stripe subscription/customer reference. No invoices were found for the requested filters. |
 | <a id="bck-stripe-0018"></a>`BCK.STRIPE.0018` | 400 | integration | — | Error retrieving Stripe payment metadata | Inspect Stripe dashboard logs for the request id we return in params. PaymentIntent metadata retrieval failed — usually a transient Stripe API issue. |
 | <a id="bck-stripe-0019"></a>`BCK.STRIPE.0019` | 400 | integration | — | Error retrieving Stripe balance | Inspect Stripe dashboard logs for the request id we return in params. Balance retrieval failed — usually a Connect-account configuration or scope issue. |
 | <a id="bck-stripe-0020"></a>`BCK.STRIPE.0020` | 500 | integration | — | Error canceling subscription | Inspect Stripe dashboard logs for the request id we return in params. Subscription cancellation failed — verify the subscription belongs to the right Connect account. |
 | <a id="bck-stripe-0021"></a>`BCK.STRIPE.0021` | 400 | integration | — | Unable to create Stripe subscription | Inspect Stripe dashboard logs for the request id we return in params. Subscription create failed — usually a missing customer default payment method or invalid price. |
 | <a id="bck-stripe-0022"></a>`BCK.STRIPE.0022` | 424 | integration | — | The settlement could not be executed because the seller account has not properly configured the payment service provider (Stripe) | The plan seller has not completed Stripe Connect onboarding (charges_enabled is false). Ask the seller to finish onboarding before retrying the settlement. |
 | <a id="bck-stripe-0023"></a>`BCK.STRIPE.0023` | 503 | integration | — | Transient failure while looking up the seller payment service provider configuration | Inspect the underlying error in logs. The seller PSP-configuration lookup failed transiently — retry; if it persists, check DB connectivity. |
 | <a id="bck-stripe-0024"></a>`BCK.STRIPE.0024` | 424 | integration | ❌ | The organization owning the plan you are trying to purchase has not configured its payment service provider (Stripe). Contact the organization to complete the setup before retrying the purchase. | The plan is owned by an organization that has not connected Stripe (or has not completed Connect onboarding) for this environment. Surface the orgId / orgName carried in params so the buyer can identify the organization to contact. |
 | <a id="bck-stripe-0030"></a>`BCK.STRIPE.0030` | 500 | integration | — | Application-fee true-up refund failed; row left Settled with the owed amount stored in providerMetadata.trueUpRefundOwedMicro for manual reconciliation | The Stripe application-fee true-up refund failed. The settlement row is left as Settled with the owed amount in providerMetadata.trueUpRefundOwedMicro for manual reconciliation through Stripe Dashboard. |
 | <a id="bck-stripe-0031"></a>`BCK.STRIPE.0031` | 500 | internal | ❌ | Price conversion overflow when converting micro-units to cents | The plan price exceeds Number.MAX_SAFE_INTEGER after conversion. Lower the plan price or fix the unit boundary in convertMicroUnitsToCents. |
 | <a id="bck-stripe-0032"></a>`BCK.STRIPE.0032` | 500 | integration | ❌ | Stripe checkout: user profile not found for account event | The Stripe account event referenced a user that no longer exists in our DB (deleted profile, or environment mismatch between live/sandbox). The webhook is marked permanent so Stripe stops retrying. |
 | <a id="bck-stripe-0033"></a>`BCK.STRIPE.0033` | 500 | integration | ✅ | Stripe account webhook handler failed | Generic catch-all for the account webhook handler — inspect the cause field for the underlying error and the params for eventId/stripeAccountId/userId. |
 | <a id="bck-stripe-0034"></a>`BCK.STRIPE.0034` | 500 | integration | ✅ | Stripe payment intent webhook handler failed | Generic catch-all for the payment intent webhook handler — inspect the cause and params.eventId. |
 | <a id="bck-stripe-0035"></a>`BCK.STRIPE.0035` | 500 | integration | ✅ | Stripe subscription invoice webhook handler failed | Generic catch-all for the subscription invoice (recurring) webhook handler — inspect the cause and params.eventId. |
 | <a id="bck-stripe-0036"></a>`BCK.STRIPE.0036` | 400 | business | ❌ | Stripe subscription creation: plan has no Stripe priceId | The plan DDO is missing metadata.plan.priceId. Re-publish the plan with a Stripe price configured, or use the one-shot payment intent flow. |
 | <a id="bck-stripe-0037"></a>`BCK.STRIPE.0037` | 400 | integration | ✅ | Stripe subscription creation: no latest invoice on subscription | The newly-created subscription did not return a latest_invoice. Retry once; if it persists, check Stripe dashboard for the subscription state. |
 | <a id="bck-stripe-0038"></a>`BCK.STRIPE.0038` | 400 | integration | ✅ | Stripe subscription creation: no payment intent on subscription | The subscription invoice did not yield a payment_intent. This usually means the customer has no default payment method. Confirm the SetupIntent has succeeded before creating the subscription. |
 | <a id="bck-stripe-0039"></a>`BCK.STRIPE.0039` | 400 | business | ❌ | No Stripe account connected | The authenticated user has no personal Stripe account and belongs to no organization with one connected. Connect a Stripe account (Profile or Organization → Details) before requesting the account balance. |
 
 ## <span id="bck-stripe-connect"></span>`BCK.STRIPE.CONNECT`
 
 | Code | HTTP | Category | Retryable | Message | Hint |
 |---|---|---|---|---|---|
 | <a id="bck-stripe-connect-0001"></a>`BCK.STRIPE.CONNECT.0001` | 503 | integration | — | Stripe Connect is not configured | `STRIPE_CONNECT_CLIENT_ID` is unset. Configure Stripe Connect credentials in the environment before enabling Connect features. |
 | <a id="bck-stripe-connect-0002"></a>`BCK.STRIPE.CONNECT.0002` | 400 | integration | — | Stripe OAuth token exchange failed | Inspect Stripe dashboard logs for the request id we return in params. The OAuth code exchange failed — usually a mismatched redirect_uri or expired code. |
 | <a id="bck-stripe-connect-0003"></a>`BCK.STRIPE.CONNECT.0003` | 400 | integration | — | Stripe OAuth response missing stripe_user_id | Stripe returned a successful OAuth response without stripe_user_id. Treat as a Stripe API anomaly and restart the OAuth flow. |
 | <a id="bck-stripe-connect-0004"></a>`BCK.STRIPE.CONNECT.0004` | 400 | integration | — | Stripe account environment does not match platform environment | The connected account is in a different Stripe environment (sandbox vs live) than the platform. Re-connect using the platform’s matching environment. |
 | <a id="bck-stripe-connect-0005"></a>`BCK.STRIPE.CONNECT.0005` | 404 | integration | — | User profile not found for Stripe Connect update | Verify the user-profile id in params. The OAuth callback fired for a user that no longer has a profile row — likely a deleted account. |
 | <a id="bck-stripe-connect-0006"></a>`BCK.STRIPE.CONNECT.0006` | 409 | integration | — | Organization Stripe scope could not be resolved | An organization-scoped connect/disconnect was requested but the organization could not be resolved for the caller (deactivated, membership revoked mid-flow, or a transient lookup error). We refuse rather than fall back to the personal profile so the scopes stay independent — retry once the membership/org is available. |
 | <a id="bck-stripe-connect-0007"></a>`BCK.STRIPE.CONNECT.0007` | 400 | validation | — | Organization Stripe connect requires an organization id | An organization-origin connect was requested without an orgId. Pass the orgId of the workspace to connect (admin membership required); the personal flow is served without an orgId. |
 | <a id="bck-stripe-connect-0008"></a>`BCK.STRIPE.CONNECT.0008` | 400 | validation | — | orgId is not supported together with a supplied stripeAccountId | Organization scoping is applied by stamping metadata on a freshly-created Express account, which is not possible for a caller-supplied existing account. Either omit orgId (personal account) or omit stripeAccountId (let us create the org-scoped Express account). |
 
 ## <span id="bck-transcoding"></span>`BCK.TRANSCODING`
 
 | Code | HTTP | Category | Retryable | Message | Hint |
 |---|---|---|---|---|---|
 | <a id="bck-transcoding-0001"></a>`BCK.TRANSCODING.0001` | 404 | integration | — | UGC not found | Verify the UGC asset id. The asset may have been deleted, or transcoding has not finished yet for newly uploaded media. |
 | <a id="bck-transcoding-0002"></a>`BCK.TRANSCODING.0002` | 404 | business | ❌ | Transcoded asset not found for the given UGC id | Verify the UGC id in params. The queue row may have been pruned, or the upload never reached the transcoder. |
 | <a id="bck-transcoding-0003"></a>`BCK.TRANSCODING.0003` | 500 | integration | ❌ | Transcoding failed for UGC asset | Inspect the underlying error in logs. The transcoder marked this asset Errored — usually a codec/format issue or storage failure. Re-upload after fixing the source. |
 | <a id="bck-transcoding-0004"></a>`BCK.TRANSCODING.0004` | 503 | integration | ✅ | Transcoding is still in progress for UGC asset | The transcoder has not finished encoding this asset. Retry after a short backoff; the worker typically completes within seconds for small assets. |
 
 ## <span id="bck-txs"></span>`BCK.TXS`
 
 | Code | HTTP | Category | Retryable | Message | Hint |
 |---|---|---|---|---|---|
 | <a id="bck-txs-0001"></a>`BCK.TXS.0001` | 404 | integration | — | Error searching asset transactions by id | Verify the asset/transaction id. Empty transaction lookups return 404 by design. |
 | <a id="bck-txs-0002"></a>`BCK.TXS.0002` | 404 | integration | — | Error searching asset consumer transactions | Verify the consumer address and asset id. Empty result sets return 404 by design. |
 | <a id="bck-txs-0003"></a>`BCK.TXS.0003` | 404 | integration | — | Error searching distintc asset transactions | Verify the asset id. Empty distinct-asset transaction lookups return 404. |
 | <a id="bck-txs-0004"></a>`BCK.TXS.0004` | 404 | integration | — | Error searching plan transactions | Verify the planId. Empty plan-transaction lookups return 404 by design. |
 | <a id="bck-txs-0005"></a>`BCK.TXS.0005` | 404 | integration | — | Error searching asset transactions grouped by owner | Verify the owner address. Empty owner-grouped transaction lookups return 404. |
 | <a id="bck-txs-0006"></a>`BCK.TXS.0006` | 404 | integration | — | Error gathering DDO Info | Verify the DID is well-formed and registered. DDO resolution failures bubble up as 404 here. |
 | <a id="bck-txs-0007"></a>`BCK.TXS.0007` | 404 | integration | — | Error getting active users for owner | Verify the owner address. Empty active-users lookups return 404 by design. |
 | <a id="bck-txs-0008"></a>`BCK.TXS.0008` | 404 | integration | — | Error getting total API calls for owner | Verify the owner address. Empty total-calls lookups return 404 by design. |
 | <a id="bck-txs-0009"></a>`BCK.TXS.0009` | 404 | integration | — | Error getting total revenue for owner | Verify the owner address. Empty total-revenue lookups return 404 by design. |
 | <a id="bck-txs-0010"></a>`BCK.TXS.0010` | 404 | integration | — | Error getting dashboard metrics for owner | Verify the owner address. Empty dashboard-metrics lookups return 404 by design. |
 | <a id="bck-txs-0011"></a>`BCK.TXS.0011` | 500 | integration | — | Error getting revenue time-series for owner | Transient server-side error building the revenue time-series; safe to retry. Inputs are validated upstream (invalid dates return 400, granularity is normalized), so this is not a bad-request issue. |
 | <a id="bck-txs-0012"></a>`BCK.TXS.0012` | 500 | integration | — | Error getting requests time-series for owner | Transient server-side error building the requests time-series; safe to retry. Inputs are validated upstream (invalid dates return 400, granularity is normalized), so this is not a bad-request issue. |
 | <a id="bck-txs-0013"></a>`BCK.TXS.0013` | 400 | business | — | startDate/endDate must be valid ISO-8601 timestamps | Pass startDate/endDate as ISO-8601 strings, e.g. 2024-01-01T00:00:00.000Z. |
 
 ## <span id="bck-user_profile"></span>`BCK.USER_PROFILE`
 
 | Code | HTTP | Category | Retryable | Message | Hint |
 |---|---|---|---|---|---|
 | <a id="bck-user_profile-0001"></a>`BCK.USER_PROFILE.0001` | 500 | internal | ❌ | User profile not found | A profile lookup returned null where a row was expected. Two known throw sites: DTO mappers asserting a non-null entity, and the org-tier bootstrap requiring the node-account system user. Inspect the throw-site `details` for the specific context. Legacy callers depended on this surfacing as 500; the canonical "user profile not found for caller-supplied identifier" lookup-not-found semantics live in `BCK.USER_PROFILE.0002` (404). |
 | <a id="bck-user_profile-0002"></a>`BCK.USER_PROFILE.0002` | 404 | business | ❌ | User profile not found | Verify the user identifier. The profile may have been disabled or never created. |
@@ -641,31 +643,31 @@
 
 ## <span id="bck-version"></span>`BCK.VERSION`
 
 | Code | HTTP | Category | Retryable | Message | Hint |
 |---|---|---|---|---|---|
 | <a id="bck-version-0001"></a>`BCK.VERSION.0001` | 400 | validation | ❌ | Unknown or unsupported API version | Send Nevermined-Version as MAJOR.MINOR (e.g. "1.0") within the supported range. GET /api/v1/meta/versions lists the supported range; see https://nevermined.ai/docs/development-guide/api-versioning. |
 | <a id="bck-version-0002"></a>`BCK.VERSION.0002` | 500 | internal | ❌ | API version transformation failed | A server-side version gate failed to reshape the request/response for your pinned API version. This is a backend bug — quote the correlation id when reporting it. |
 
 ## <span id="bck-vgs"></span>`BCK.VGS`
 
 | Code | HTTP | Category | Retryable | Message | Hint |
 |---|---|---|---|---|---|
 | <a id="bck-vgs-0001"></a>`BCK.VGS.0001` | 503 | integration | ❌ | Unified card enrolment is not available (VGS vault not configured) | #2057 item 2: VgsVaultAvailableGuard rejected the unified VGS-Collect enrol/enroll-session call because the shared VGS vault (VGS_* / vgsAgentic.* env) is unconfigured. Same underlying state as BCK.VISA.0001, but VGS-namespaced so a unified-card 503 is not mis-attributed to a Visa-agentic outage. Configure the VGS vault credentials before enabling the unified card rail. |
 | <a id="bck-vgs-0002"></a>`BCK.VGS.0002` | 502 | integration | ❌ | VGS network-token provision-on-create failed | #2151: provisioning a portable network token for a freshly enrolled unified VGS card failed. This is the internal per-rail LOG marker emitted immediately BEFORE the enrolment is rolled back — a `vgs` card is worthless without an active network token, so the failure is NO LONGER swallowed (superseded the best-effort behaviour). The client sees BCK.VGS.0004 (permanent/config) or BCK.VGS.0005 (transient). The unified-rail twin of BCK.VISA.0021 (Visa-agentic rail): split out so an alert can pinpoint which rail dropped a token. Inspect cardId in the log context. |
 | <a id="bck-vgs-0003"></a>`BCK.VGS.0003` | 401 | auth | ❌ | Invalid or expired card enrolment session | #2057 item 1: the enrol-session token replayed on POST /api/v1/delegation/enroll was missing, malformed, expired, wrong-audience, or minted for a different user. The browser must first GET /api/v1/delegation/enroll-session (authenticated) and forward the returned enrollSessionToken. Message is intentionally generic — the specific jwt.verify reason is a forgery oracle and stays in the server logs only. |
 | <a id="bck-vgs-0004"></a>`BCK.VGS.0004` | 500 | integration | ❌ | Card not enrolled — a network token could not be provisioned | The card could not be enrolled and nothing was saved. Please try again later, or contact support if the problem persists. |
 | <a id="bck-vgs-0005"></a>`BCK.VGS.0005` | 502 | integration | ✅ | Card not enrolled — network-token provisioning is temporarily unavailable | The card could not be enrolled due to a temporary issue. Please try again shortly. |
 
 ## <span id="bck-visa"></span>`BCK.VISA`
 
 | Code | HTTP | Category | Retryable | Message | Hint |
 |---|---|---|---|---|---|
 | <a id="bck-visa-0001"></a>`BCK.VISA.0001` | 503 | integration | — | Visa payment provider is not configured | VGS_* env vars are unset. Configure the VGS vault credentials before enabling Visa Agentic Token features. |
 | <a id="bck-visa-0002"></a>`BCK.VISA.0002` | 502 | integration | — | Visa card enrollment failed | Inspect VGS dashboard logs for the enrollment id in params. Common causes: invalid card details, sanctions/AVS reject, or vault routing. |
 | <a id="bck-visa-0003"></a>`BCK.VISA.0003` | 502 | integration | — | Visa mandate creation failed | Inspect VGS dashboard logs for the mandate id in params. Mandate creation may fail when consumerPrompt/assuranceData are missing or the card is non-eligible. |
 | <a id="bck-visa-0004"></a>`BCK.VISA.0004` | 502 | integration | — | VGS cryptogram issuance failed | Inspect VGS dashboard logs for the cryptogram request id in params. Common causes: vault session expired, card revoked, or merchant data mismatch. |
 | <a id="bck-visa-0005"></a>`BCK.VISA.0005` | 400 | integration | — | Invalid VGS webhook signature | Verify the `VGS_WEBHOOK_SECRET` in env matches the secret configured in VGS dashboard. Replayed or forged webhooks land here. |
 | <a id="bck-visa-0006"></a>`BCK.VISA.0006` | 502 | integration | — | VGS OAuth2 client_credentials request failed | Inspect VGS dashboard logs. The OAuth2 client_credentials call failed — usually expired credentials or the wrong `VGS_BASE_URL`. |
 | <a id="bck-visa-0007"></a>`BCK.VISA.0007` | 502 | integration | — | Stripe settlement of Visa virtual card failed | Inspect Stripe dashboard for the PaymentIntent id in params. The Stripe settlement of the VGS-issued virtual card failed at the Stripe side. |
 | <a id="bck-visa-0008"></a>`BCK.VISA.0008` | 400 | integration | — | User has no email on file (required for Visa enrolment) | Capture or update the user email before retrying Visa enrolment. Visa requires a deliverable email for the cardholder. |
 | <a id="bck-visa-0009"></a>`BCK.VISA.0009` | 422 | integration | — | Visa mandate (intent) not provisioned for this delegation | Re-issue the delegation via the Visa flow so a mandate (Visa intent) is provisioned. Without it the card cannot be used for spending. |
@@ -673,35 +675,35 @@
 | <a id="bck-visa-0011"></a>`BCK.VISA.0011` | 400 | integration | — | VGS webhook payload malformed | Inspect the underlying VGS payload structure. Required fields are missing or have the wrong shape — usually a VGS API version mismatch. |
 | <a id="bck-visa-0012"></a>`BCK.VISA.0012` | 400 | integration | — | VGS webhook revoke event missing card identifier | The revoke webhook is missing the card identifier we need to flip our DB state. Inspect VGS to confirm the event payload and replay manually if needed. |
 | <a id="bck-visa-0013"></a>`BCK.VISA.0013` | 500 | integration | — | Unable to process VGS webhook | Inspect the underlying error and webhook event id in params. The handler crashed mid-processing; VGS will retry the webhook. |
 | <a id="bck-visa-0014"></a>`BCK.VISA.0014` | 400 | business | — | Visa delegation creation requires consumerPrompt and assuranceData | Provide both consumerPrompt and assuranceData when creating a Visa delegation. These are required by the Visa Trusted Agent Protocol. |
 | <a id="bck-visa-0015"></a>`BCK.VISA.0015` | 400 | business | — | Visa delegation requires planId — mandate must bind to a single plan seller | Provide planId when creating a Visa delegation. Visa mandates must bind to a single plan seller for compliance with the Trusted Agent Protocol. |
 | <a id="bck-visa-0016"></a>`BCK.VISA.0016` | 400 | business | — | Plan seller has not completed Stripe Connect onboarding required for Visa delegations | The plan seller must complete Stripe Connect onboarding before accepting Visa delegations. Ask the seller to finish onboarding. |
 | <a id="bck-visa-0017"></a>`BCK.VISA.0017` | 502 | integration | — | Stripe Connect account lookup failed while resolving Visa merchant context | Inspect Stripe dashboard logs for the connected account id in params. Connect account lookup failed transiently — retry; if it persists, check the seller’s Connect status. |
 | <a id="bck-visa-0018"></a>`BCK.VISA.0018` | 409 | business | — | This card is already enrolled to a different account | Deprecated: no longer thrown. Visa enrolment no longer rejects a card already on file under another account (RFC-1 relaxed uniqueness, epic #1958). |
 | <a id="bck-visa-0019"></a>`BCK.VISA.0019` | 500 | internal | ❌ | Visa provider misconfigured for this environment | The Visa provider is otherwise wired but VGS_AGENTIC_BROWSER_CLIENT_ID/SECRET are missing. The browser-token endpoint would silently fall back to the privileged backend service account in this state. Provision the narrower Client-Side Service Account or unset the Visa env vars to disable the provider. See VIS-011 in security audit 2026-05-27. |
-| <a id="bck-visa-0020"></a>`BCK.VISA.0020` | 502 | integration | ❌ | VGS GA Network-Token rail call failed | A server-to-server VGS GA Network-Token operation failed — provisioning a network token (POST /cards/{id}/network-tokens) or minting a GA cryptogram (POST /cards/{id}/cryptogram). Inspect cardId, status, and detail in params. This is the GA rail (no device binding), distinct from the Agentic-Tokens rail (BCK.VISA.0004). |
+| <a id="bck-visa-0020"></a>`BCK.VISA.0020` | 502 | integration | ❌ | VGS GA Network-Token rail call failed | A server-to-server VGS GA Network-Token operation failed — provisioning a network token (POST /cards/&#123;id&#125;/network-tokens) or minting a GA cryptogram (POST /cards/&#123;id&#125;/cryptogram). Inspect cardId, status, and detail in params. This is the GA rail (no device binding), distinct from the Agentic-Tokens rail (BCK.VISA.0004). |
 | <a id="bck-visa-0021"></a>`BCK.VISA.0021` | 502 | integration | ❌ | VGS network-token provision-on-create failed (best-effort) | Provisioning a portable network token for a freshly enrolled VGS-canonical card failed (epic #1958, T2.A / #1976). This is BEST-EFFORT and never surfaced to the client: enrolment completes, the credential persists with networkToken NULL, and the charge path falls back to the legacy/instrument rail. Used as a stable code on the swallowed log line so the gap is alertable and backfill-able. Inspect cardId/credentialId in the log context. |
 
 ## <span id="bck-widget"></span>`BCK.WIDGET`
 
 | Code | HTTP | Category | Retryable | Message | Hint |
 |---|---|---|---|---|---|
 | <a id="bck-widget-0001"></a>`BCK.WIDGET.0001` | 500 | business | — | Unable to store widget config | Inspect the underlying error in logs. Widget config persistence failed — usually a DB-layer or storage-layer error. |
 | <a id="bck-widget-0002"></a>`BCK.WIDGET.0002` | 404 | business | — | Unable to get widget config from id | Verify the widget id. The widget may have been deleted or never created. |
 | <a id="bck-widget-0003"></a>`BCK.WIDGET.0003` | 403 | business | ❌ | The user doesnt own this widget | Only the wallet that created the widget can edit or delete its config. Re-authenticating as the same caller will not help. |
 | <a id="bck-widget-0004"></a>`BCK.WIDGET.0004` | 500 | business | — | Error updating widget config | Inspect the underlying error in logs. Widget update failed — usually a DB-layer error or validation reject on the new config. |
 | <a id="bck-widget-0005"></a>`BCK.WIDGET.0005` | 500 | business | — | Error deleting widget config | Inspect the underlying error in logs. Widget deletion failed — usually a DB-layer error. |
 
 ## <span id="bck-widget_keys"></span>`BCK.WIDGET_KEYS`
 
 | Code | HTTP | Category | Retryable | Message | Hint |
 |---|---|---|---|---|---|
 | <a id="bck-widget_keys-0001"></a>`BCK.WIDGET_KEYS.0001` | 500 | internal | ❌ | Widget key generation failed | Inspect the underlying error in logs. Widget-key minting failed — usually a DB-write error. |
 | <a id="bck-widget_keys-0002"></a>`BCK.WIDGET_KEYS.0002` | 404 | auth | — | Widget key not found | Verify the widget-key id and that it belongs to the caller organisation. Revoked keys also surface as not-found. |
 
 ## <span id="bck-widget_session"></span>`BCK.WIDGET_SESSION`
 
 | Code | HTTP | Category | Retryable | Message | Hint |
 |---|---|---|---|---|---|
 | <a id="bck-widget_session-0001"></a>`BCK.WIDGET_SESSION.0001` | 401 | auth | — | Invalid widget credentials | F-055: covers both "org has no active widget key" and "secret rejected". The integrator backend must send the active `wk_...` secret as `rawSecret` in `POST /widgets/session`; if the org never generated a key, create one in the admin UI first. A single error code is returned so an attacker probing the public endpoint cannot distinguish the two cases. |
 | <a id="bck-widget_session-0003"></a>`BCK.WIDGET_SESSION.0003` | 500 | auth | — | Widget JWT secret not configured | Configure `WIDGET_JWT_SECRET` in the deployment env. The widget-session JWT signer requires this secret to be set. |
@@ -712,34 +714,34 @@
 | <a id="bck-widget_session-0010"></a>`BCK.WIDGET_SESSION.0010` | 401 | auth | — | Widget session token is missing required widgetKeyId claim | Reissue the session token with the widgetKeyId claim populated. The widget runtime expects a widgetKeyId for revocation checks. |
 | <a id="bck-widget_session-0011"></a>`BCK.WIDGET_SESSION.0011` | 401 | auth | — | Widget key has been revoked or no longer exists | Generate a fresh widget key in the org admin UI. Revoked keys cannot resume existing sessions; the embed must be updated. |
 | <a id="bck-widget_session-0012"></a>`BCK.WIDGET_SESSION.0012` | 403 | auth | — | Origin not allowed for this widget key | Add the requesting origin to the widget key’s allowed-origins list, or embed the widget from an approved origin. |
 | <a id="bck-widget_session-0013"></a>`BCK.WIDGET_SESSION.0013` | 400 | auth | — | Widget session request is missing the required email field | The integrator backend must forward the end-user email in the `email` field of POST /widgets/session. Email is the canonical Nevermined identity for widget users. |
 | <a id="bck-widget_session-0018"></a>`BCK.WIDGET_SESSION.0018` | 403 | auth | — | Card setup is only available to organization members | The authenticated user has no active organization membership — `POST /widgets/session/self` is the org-scoped (members-only) widget path. To enroll a card or create a delegation as a buyer/agent, use the open embedded flow instead: `POST /api/v1/embed/session` (then open the embed app card-setup page with the returned sessionToken). |
 | <a id="bck-widget_session-0019"></a>`BCK.WIDGET_SESSION.0019` | 403 | auth | — | orgId is not one of the caller’s organization memberships | Pass an `orgId` the authenticated user is a member of — list your memberships via `/organizations/my-memberships` or the org switcher in the dashboard. To enroll a card or create a delegation as a buyer/agent (no org), use the open embedded flow: `POST /api/v1/embed/session` (then open the embed app card-setup page with the returned sessionToken). |
 | <a id="bck-widget_session-0020"></a>`BCK.WIDGET_SESSION.0020` | 403 | auth | — | Agent or plan does not belong to the widget session’s organization | The embed checkout can only purchase agents/plans owned by the organization the widget session was minted for. Verify the `agentId`/`planId` in the embed URL belongs to that organization. |
 
 ## <span id="bck-x402"></span>`BCK.X402`
 
 | Code | HTTP | Category | Retryable | Message | Hint |
 |---|---|---|---|---|---|
 | <a id="bck-x402-0001"></a>`BCK.X402.0001` | 404 | business | — | Agent not found | Verify the agentId in the x402 facilitator-resource URL. Agents that are deactivated or in a different environment surface as not-found here. |
 | <a id="bck-x402-0002"></a>`BCK.X402.0002` | 404 | business | — | Plan not found | Verify the planId in the x402 facilitator-resource URL. Plans that are deactivated or in a different environment surface as not-found here. |
 | <a id="bck-x402-0003"></a>`BCK.X402.0003` | 400 | business | — | The plan is not associated to the agent | Re-link the plan to the agent before retrying, or use a different plan that is already linked. x402 requires an explicit (agent, plan) edge. |
 | <a id="bck-x402-0004"></a>`BCK.X402.0004` | 500 | business | — | Error generating X402 access token | Inspect the underlying error in logs. x402 access-token minting failed — usually a JWT signing key issue or an upstream chain RPC error. |
 | <a id="bck-x402-0005"></a>`BCK.X402.0005` | 402 | business | — | Invalid access token | Mint a fresh access token via the x402 /generate-token endpoint. Expired or tampered tokens land here. |
 | <a id="bck-x402-0006"></a>`BCK.X402.0006` | 500 | business | — | Error verifying permissions | Inspect the underlying error in logs. The verifyPermissions call failed — usually a transient DB error; retry once. Persistent failures may indicate a stale plan-permissions cache. |
 | <a id="bck-x402-0007"></a>`BCK.X402.0007` | 500 | business | — | Failed to order Pay-as-you-go plan | Inspect the underlying error in logs. Pay-as-you-go plan ordering failed — usually a delegation/credit issue on the buyer side or an upstream chain RPC error. |
 | <a id="bck-x402-0008"></a>`BCK.X402.0008` | 500 | business | — | Failed to order crypto plan | Inspect the underlying error in logs. Crypto plan ordering failed — usually a buyer balance/approval issue or a chain RPC revert. |
 | <a id="bck-x402-0009"></a>`BCK.X402.0009` | 500 | business | — | Failed to redeem credits | Inspect the underlying error in logs. Credit redemption failed mid-way — the buyer may have been charged but not credited; check the activity feed and reconcile manually if needed. |
 | <a id="bck-x402-0010"></a>`BCK.X402.0010` | 400 | business | — | Invalid x402 access token | Mint a fresh access token via the x402 /generate-token endpoint. The supplied token is malformed or signed by an unknown key. |
 | <a id="bck-x402-0011"></a>`BCK.X402.0011` | 404 | business | — | User profile not found | Verify the buyer wallet has a user-profile row. New wallets must complete the signup flow before purchasing via x402. |
 | <a id="bck-x402-0012"></a>`BCK.X402.0012` | 400 | business | — | resource.url is required when agentId is provided | Pass resource.url alongside agentId in the x402 settlement body. The URL is required for routing the settlement to the right merchant. |
 | <a id="bck-x402-0013"></a>`BCK.X402.0013` | 400 | business | — | Accepted payment method does not match requirements | Pass an accepted payment method that matches the plan’s configured currency/scheme. The combinations are documented per-plan in the plan metadata. |
 | <a id="bck-x402-0014"></a>`BCK.X402.0014` | 400 | business | — | Delegation restricted to a different plan | Reuse the delegation only with the planId it was originally bound to, or create a fresh delegation for the new plan. Visa mandates are plan-scoped. |
 | <a id="bck-x402-0015"></a>`BCK.X402.0015` | 404 | business | ❌ | Permission not found | The permission record either has been revoked or never existed for this combination of (subscriber, plan, agent). |
 | <a id="bck-x402-0016"></a>`BCK.X402.0016` | 400 | business | ❌ | Permission is already revoked | The permission was already revoked. No further action required. |
 | <a id="bck-x402-0017"></a>`BCK.X402.0017` | 500 | internal | ❌ | Failed to issue credits after card charge | The card was charged successfully but the DB-side mint of credits failed. The charge is auto-refunded when the provider supports it; otherwise a `failed_post_charge_*` delegationTransactions row is left for manual reconciliation. |
 | <a id="bck-x402-0018"></a>`BCK.X402.0018` | 500 | internal | ❌ | Invalid amountCents derived from order | A defensive arithmetic check in the erc4337 settlement path produced a non-finite or negative cents amount. Inspect the order amount and currency in params; this should never happen for legitimate orders. |
 | <a id="bck-x402-0019"></a>`BCK.X402.0019` | 402 | business | ❌ | Delegation not found | No delegation with this id is owned by the caller — it either never existed or belongs to someone else (the two are intentionally indistinguishable). Verify the delegationId, or create a fresh delegation. Revoked/expired/exhausted delegations report BCK.X402.0020/0021/0022 instead. |
 | <a id="bck-x402-0020"></a>`BCK.X402.0020` | 402 | business | ❌ | Delegation is revoked | This delegation has been revoked and can no longer be used. Create a new card delegation to continue. |
 | <a id="bck-x402-0021"></a>`BCK.X402.0021` | 402 | business | ❌ | Delegation has expired | The delegation passed its expiry. Mint a new one (omit `delegationId` and resubmit with the payment method plus `spendingLimitCents` and `durationSecs`). |
 | <a id="bck-x402-0022"></a>`BCK.X402.0022` | 402 | business | ❌ | Delegation budget exhausted | The delegation has reached its spending limit or maximum transaction count. Create a new delegation with a higher `spendingLimitCents` / `maxTransactions` to keep transacting. |
@@ -751,26 +753,26 @@
 | <a id="bck-x402-0028"></a>`BCK.X402.0028` | 402 | business | ❌ | Payment method is revoked | The payment method has been revoked. Add or re-enable a payment method in the dashboard and retry with its identifier. |
 | <a id="bck-x402-0029"></a>`BCK.X402.0029` | 402 | business | ❌ | API key not authorized for this delegation or payment method | The API key used is not in the allow-list for this delegation / payment method. Use an authorized API key, or update the payment method allowedApiKeyIds to include it. |
 | <a id="bck-x402-0030"></a>`BCK.X402.0030` | 402 | business | ❌ | Required token-generation input is missing or incomplete | A required input for issuing the access token is missing. Provide `accepted.planId`, and a complete `delegationConfig`: reuse with `{ delegationId }`, or create with `{ providerPaymentMethodId \| cardId, spendingLimitCents, durationSecs }` (optionally `currency`). The per-failure `details` names the specific missing field. |
 | <a id="bck-x402-0034"></a>`BCK.X402.0034` | 402 | business | ❌ | Unsupported scheme or currency | The requested payment scheme or currency is not supported. Check the plan configured scheme/currency (e.g. Visa delegations support only usd / eur) and resubmit with a supported combination. |
 | <a id="bck-x402-0035"></a>`BCK.X402.0035` | 402 | business | ❌ | No session keys found for delegation | The delegation is owned by the caller and usable, but its linked erc4337 permission is missing session keys (burnSessionKey / orderSessionKey). This is a data-integrity issue — the delegation was likely created without completing session-key provisioning. Create a fresh crypto delegation; if it recurs, report the delegationId for investigation. |
 | <a id="bck-x402-0036"></a>`BCK.X402.0036` | 402 | business | ❌ | Delegation not usable (unknown lifecycle state) | The delegation is in a lifecycle state the server does not recognise as usable. Create a fresh delegation to continue; if this persists, report the delegationId for investigation. |
 | <a id="bck-x402-0037"></a>`BCK.X402.0037` | 403 | business | ❌ | SetupIntent does not belong to the authenticated user | The SetupIntent was created by (or for) a different user. Re-create the SetupIntent under the authenticated account and finalize enrollment with that id. |
 | <a id="bck-x402-0038"></a>`BCK.X402.0038` | 409 | business | ❌ | SetupIntent is not in the expected state | The SetupIntent has not reached status "succeeded" (it may still be processing, or it failed). Confirm the card on the client, wait for "succeeded", then finalize enrollment. |
 | <a id="bck-x402-0039"></a>`BCK.X402.0039` | 422 | business | ❌ | SetupIntent has no associated payment method | The SetupIntent succeeded but carries no payment method. Re-run the card setup so a payment method is attached, then finalize enrollment. |
 | <a id="bck-x402-0040"></a>`BCK.X402.0040` | 404 | business | ❌ | API Key not found for this user | One of the supplied `allowedApiKeyIds` does not belong to this user (the offending skId is in `params`). Remove or correct it and retry. |
 | <a id="bck-x402-0041"></a>`BCK.X402.0041` | 409 | business | ❌ | API Key is not active | One of the supplied `allowedApiKeyIds` is revoked/inactive (the offending skId is in `params`). Use an active key or re-enable it, then retry. |
 | <a id="bck-x402-0042"></a>`BCK.X402.0042` | 500 | internal | ❌ | VGS outbound proxy is misconfigured | Server-side configuration fault (the VGS outbound proxy is unset, not HTTPS, has an invalid URL, or points at a non-VGS host). The caller did nothing wrong. Fix the VGS proxy configuration; if it persists, report the correlationId. |
 | <a id="bck-x402-0043"></a>`BCK.X402.0043` | 502 | integration | ❌ | Card enrollment via VGS failed | The upstream VGS→Stripe card-creation call returned bad data or a non-200 status. Inspect VGS / Stripe logs for the correlationId. Usually invalid card details or a vault-routing issue; retry after correcting the card, or report if it persists. |
 | <a id="bck-x402-0044"></a>`BCK.X402.0044` | 500 | internal | ❌ | Invalid internal identifier format | An internal invariant failed (a userId did not match the expected format for downstream metadata). This is a server-side fault, not a client input error. Report the correlationId for investigation. |
 | <a id="bck-x402-0045"></a>`BCK.X402.0045` | 501 | internal | ❌ | Network-token charging is not supported by this payment provider | This provider cannot yet charge from a network token + cryptogram. Today only the Visa rail does. Stripe gains a native network-token field in #1979 (T2.D) and Braintree gains BYOT in #1978 (T2.C); until then the router must not dispatch a network-token charge to these providers. |
 | <a id="bck-x402-0046"></a>`BCK.X402.0046` | 500 | internal | ❌ | Charge router received no candidate provider routes | Epic #1958 T1.C: the charge-time provider router (CardPaymentProviderFactory.chargeWithFallback) was called with an empty route list. The settle handler always supplies at least the legacy delegations.provider route, so an empty list is a server-side wiring regression — never a client input error. Report the correlationId for investigation. |
 | <a id="bck-x402-0047"></a>`BCK.X402.0047` | 500 | internal | ❌ | No card payment provider registered for the requested rail | Epic #1958 T1.C: CardPaymentProviderFactory.getProvider was asked for a card rail it has no provider instance for. CardProviderName aliases the growable CardSettlementProvider, so a newly-added PSP must be wired into the factory switch in the same change — an unhandled rail is a server-side wiring regression, never a client input error. Report the correlationId for investigation. |
 | <a id="bck-x402-0048"></a>`BCK.X402.0048` | 502 | integration | ❌ | Network-token charge failed ambiguously (may have charged) — not retried or rolled back | Epic #1958 T2.D: a network-token charge through the PSP failed with an AMBIGUOUS error (timeout / 5xx / network / idempotency-key reuse) — the charge may actually have gone through. To avoid a double charge the spending reservation is deliberately LEFT IN PLACE (no rollback) and no other route is attempted. Reconcile the delegation against the PSP before any manual retry; the providerTransactionId in delegation_transactions is the breadcrumb. |
 | <a id="bck-x402-0049"></a>`BCK.X402.0049` | 402 | business | ❌ | Network-token charge was declined by the payment provider | Epic #1958 T2.D: the PSP definitively declined the network-token charge (e.g. card_declined / insufficient_funds). No charge was captured, so the spending reservation is rolled back. Check the funding card or use a different payment method. |
 | <a id="bck-x402-0050"></a>`BCK.X402.0050` | 400 | validation | ❌ | Delegation currency has no settlement token on the plan network | An on-chain (erc4337) delegation must approve a real ERC-20 for its currency on the plan’s settlement network. The requested currency has no token configured on that network (e.g. EURC on Tempo, which settles only pathUSD/USDC) — minting the session key would produce a no-op approve that can never charge, so it is rejected. Pick a currency supported on the plan’s network (#1929). |
 | <a id="bck-x402-0051"></a>`BCK.X402.0051` | 503 | integration | ✅ | Chain RPC dependency temporarily unavailable during x402 verification | A transient failure of the on-chain RPC provider / bundler (5xx or unreachable) prevented an x402 verify/settle permission check from completing. Retry after a short backoff. If it persists, the RPC endpoint or its credentials may be misconfigured. The real upstream cause is captured server-side in the logs for this error id. |
 | <a id="bck-x402-0052"></a>`BCK.X402.0052` | 503 | integration | ✅ | EIP-7702 delegation could not be installed on the plan network | Installing the account’s Kernel v3.3 delegation designator on the plan’s network failed (bundler/paymaster/RPC), or a recent attempt is in its fail-closed backoff window. This is a transient infrastructure fault, not a client error — retry the request. See #2300. |
 | <a id="bck-x402-0053"></a>`BCK.X402.0053` | 404 | business | ❌ | Privy wallet no longer exists | The account’s embedded Privy wallet has been deleted, so its smart account can no longer be reconstructed. Privy states this is unrecoverable — neither Nevermined nor Privy can re-link an authentication method on the user’s behalf. The user profile survives but is no longer spendable; provision a new account. Distinct from BCK.X402.0011 ("user profile not found"), which means the profile itself is missing. See #2316. |
 | <a id="bck-x402-0054"></a>`BCK.X402.0054` | 402 | business | ❌ | account_access credential may only spend via the card-delegation scheme | This access token was minted for account-wide card spending, so it can only pay through the card-delegation scheme against its own pinned card delegation — not the crypto (nvm:erc4337) scheme, nor an inline-created or foreign delegation. Retry with the card-delegation scheme. #2568 §6.3. |
 | <a id="bck-x402-0055"></a>`BCK.X402.0055` | 500 | internal | ❌ | Internal error: account_access binding has no delegation to spend against | A server-side data-integrity condition — an account_access binding always carries a card delegation (funding is required at authorize time). A null here should be unreachable; inspect the API logs. #2578. |