API error codes - Nevermined Documentation

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.

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.

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.

Namespaces

BCK.ACCOUNT_PROVISIONING — 2 codes
BCK.AGENT — 12 codes
BCK.APIKEY — 18 codes
BCK.AUTH — 15 codes
BCK.BILLING — 18 codes
BCK.BRAINTREE — 10 codes
BCK.BUDGETS — 6 codes
BCK.CATALOG — 3 codes
BCK.COMMON — 34 codes
BCK.CREDITS — 6 codes
BCK.DELEGATION — 8 codes
BCK.ENTITLEMENTS — 2 codes
BCK.GROUPS — 12 codes
BCK.GUEST — 2 codes
BCK.INVITATIONS — 5 codes
BCK.LEGAL_DOCS — 6 codes
BCK.METRIC — 5 codes
BCK.METRICS — 1 code
BCK.NOTIF — 9 codes
BCK.OAUTH — 29 codes
BCK.OBSERVABILITY — 5 codes
BCK.ORGANIZATIONS — 36 codes
BCK.ORG_INTEGRATION — 2 codes
BCK.ORG_WALLETS — 10 codes
BCK.PAYMENT_CREDENTIAL — 4 codes
BCK.PAYPAL — 1 code
BCK.PLANS — 1 code
BCK.POINT — 19 codes
BCK.PROTOCOL — 57 codes
BCK.ROUTER — 9 codes
BCK.STRIPE — 34 codes
BCK.STRIPE.CONNECT — 8 codes
BCK.TRANSCODING — 4 codes
BCK.TXS — 13 codes
BCK.USER_PROFILE — 4 codes
BCK.VERSION — 2 codes
BCK.VGS — 5 codes
BCK.VISA — 21 codes
BCK.WIDGET — 5 codes
BCK.WIDGET_KEYS — 2 codes
BCK.WIDGET_SESSION — 13 codes
BCK.X402 — 52 codes

`BCK.ACCOUNT_PROVISIONING`

Code	HTTP	Category	Retryable	Message	Hint
`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.
`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.

`BCK.AGENT`

Code	HTTP	Category	Retryable	Message	Hint
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`BCK.AGENT.0008`	500	business	—	Error registering websocket connection	Inspect the underlying error in logs. Websocket registration failed — usually a Redis/queue-layer issue.
`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.
`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.
`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.
`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.

`BCK.APIKEY`

Code	HTTP	Category	Retryable	Message	Hint
`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.
`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.
`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.
`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.
`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.
`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.
`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).
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`BCK.APIKEY.0016`	400	validation	❌	No updatable API key fields provided	Send at least one of `name` or `apiVersion` in the PATCH body.
`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.
`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.
`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.

`BCK.AUTH`

Code	HTTP	Category	Retryable	Message	Hint
`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).
`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.
`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.
`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.
`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.
`BCK.AUTH.0006`	403	auth	❌	Caller does not belong to any organisation	Add the user as a member of the target organisation before calling admin-scoped endpoints.
`BCK.AUTH.0007`	403	auth	❌	Caller does not have administrator privileges	The caller is a member but not an admin. Promote the role via the organisation admin UI / API, or call from an admin account.
`BCK.AUTH.0008`	403	auth	❌	Caller account is not active	The user is suspended/disabled. Reactivate via the admin UI before retrying.
`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.
`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.
`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.
`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.
`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.
`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.
`BCK.AUTH.0015`	401	auth	—	Authentication required	Attach a valid `Authorization: Bearer <token>` (a Nevermined API key or a Privy identity token) and retry.

`BCK.BILLING`

Code	HTTP	Category	Retryable	Message	Hint
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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).
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.

`BCK.BRAINTREE`

Code	HTTP	Category	Retryable	Message	Hint
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.

`BCK.BUDGETS`

Code	HTTP	Category	Retryable	Message	Hint
`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.
`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.
`BCK.BUDGETS.0003`	422	business	❌	Group budget exceeded: this charge would exceed the group spend budget for the current period	The group has reached its spend budget for this period. Wait for the budget to reset, or an org admin can raise the limit.
`BCK.BUDGETS.0004`	422	validation	❌	Invalid group budget: the spending limit must be a positive number of cents	Provide spendingLimitCents as a whole number of minor units greater than 0 (e.g. “150000” for $1,500).
`BCK.BUDGETS.0005`	409	business	❌	A budget already exists for this currency in this group	Each group holds one budget per currency. Edit the existing budget for this currency, or create the budget in a different currency.
`BCK.BUDGETS.0006`	422	business	❌	No group budget is configured for this currency	An organization-wallet spend must be capped by a group budget. Add a budget in this currency to the group that shares the wallet.

`BCK.CATALOG`

Code	HTTP	Category	Retryable	Message	Hint
`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.
`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.
`BCK.CATALOG.0003`	400	validation	❌	Invalid catalog filter	The `protocol` filter must be one of: x402, mpp, rest, a2a, other.

`BCK.COMMON`

Code	HTTP	Category	Retryable	Message	Hint
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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).
`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.
`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.
`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.
`BCK.COMMON.0018`	500	internal	—	An error happened while downloading the asset files	Inspect the underlying error in logs. Asset file download failed — usually a storage-layer access issue or expired signed URL.
`BCK.COMMON.0019`	500	internal	—	An error happened while trying to mint credits	Inspect the underlying error in logs. Credit minting failed at protocol or SDK layer — verify the plan exists and the credit type matches.
`BCK.COMMON.0020`	500	internal	—	An error happened while trying to burn credits	Inspect the underlying error in logs. Credit burning failed — verify the user holds enough credits and the plan permits burning at this point.
`BCK.COMMON.0021`	404	internal	—	Unable to resolve widget metadata from DID	Verify the DID is a widget DID and exists. Widget metadata resolution returns 404 when the DID is not registered or its metadata was pruned.
`BCK.COMMON.0022`	403	internal	—	Method not supported	The endpoint or sub-feature is disabled in this deployment. Check feature-flag configuration before retrying.
`BCK.COMMON.0023`	403	internal	—	Error parsing input	Inspect the request body against the documented schema for this endpoint. The parser rejected a required field or malformed JSON.
`BCK.COMMON.0024`	401	auth	—	Could not validate the login claim	Re-issue a fresh login claim. The signed claim either has an invalid signature, an expired timestamp, or was issued for a different audience.
`BCK.COMMON.0025`	400	internal	—	Invalid UUID format in request	Provide a valid UUID v4 string in the highlighted field. Most ID parameters require canonical UUID format.
`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.
`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.
`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.
`BCK.COMMON.0029`	503	integration	✅	Database temporarily unavailable	The database is being restarted or is under maintenance. Retry the request after a short backoff.
`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.
`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.
`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.
`BCK.COMMON.0033`	404	integration	❌	Email challenge search returned no rows or the query failed	Inspect the underlying error in logs. The historical behaviour mapped any failure here to a 404; preserved for backward compatibility. A failed search usually means a DB-layer error or invalid filter combination.
`BCK.COMMON.0034`	400	validation	❌	Query parameter exceeds maximum length	A bounded query parameter (e.g. `textSearch`) was sent above its byte/character limit. Truncate the value client-side and retry. Limits exist to bound the cost of downstream filters — see the parameter description in the OpenAPI spec.

`BCK.CREDITS`

Code	HTTP	Category	Retryable	Message	Hint
`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.
`BCK.CREDITS.0002`	400	business	—	Burn amount must be positive	Send burn amount > 0. Zero or negative burns are rejected.
`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.
`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.
`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.
`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.

`BCK.DELEGATION`

Code	HTTP	Category	Retryable	Message	Hint
`BCK.DELEGATION.0001`	404	business	❌	Payment method not found	Verify the paymentMethodId. The payment method may have been removed or never existed.
`BCK.DELEGATION.0002`	404	business	❌	Delegation not found	Verify the delegationId. The delegation may have been revoked, expired, or never existed.
`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.
`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.
`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.
`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.
`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.
`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.

`BCK.ENTITLEMENTS`

Code	HTTP	Category	Retryable	Message	Hint
`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.
`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.

`BCK.GROUPS`

Code	HTTP	Category	Retryable	Message	Hint
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`BCK.GROUPS.0010`	404	business	❌	Group payment method not found	This payment method is not shared with the specified group; nothing to remove.
`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.
`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.

`BCK.GUEST`

Code	HTTP	Category	Retryable	Message	Hint
`BCK.GUEST.0001`	400	validation	❌	Invalid guest account request	Check the request body — guest provisioning requires either fingerprint or externalId.
`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.

`BCK.INVITATIONS`

Code	HTTP	Category	Retryable	Message	Hint
`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.
`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.
`BCK.INVITATIONS.0003`	404	business	❌	Invitation token is invalid or has expired	Invitations expire 7 days after creation. Ask the org Admin to resend the invitation, which mints a fresh token.
`BCK.INVITATIONS.0004`	403	business	❌	Email mismatch: the invitation was sent to a different email address	Sign in with the email address the invitation was sent to. Invitations are bound to a specific email and cannot be redirected.
`BCK.INVITATIONS.0005`	400	validation	❌	Role not allowed: only Admin and Member roles are permitted for invitations	Pass role=Admin or role=Member. Other role values (e.g. Owner) are not assignable via invitation.

`BCK.LEGAL_DOCS`

Code	HTTP	Category	Retryable	Message	Hint
`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.
`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.
`BCK.LEGAL_DOCS.0003`	422	business	—	Submitted legal document version is not the current effective version	Submit consent against the current effective version. The version in the request is older or newer than what the system is currently asking for.
`BCK.LEGAL_DOCS.0004`	412	business	—	Legal consent is required for the current document versions	Have the user accept the current legal documents before retrying. The endpoint is gated on up-to-date consent.
`BCK.LEGAL_DOCS.0005`	500	internal	❌	Authenticated request without a resolvable user identity	This is a server-side identity-resolution failure; retrying will not help. If it persists, contact support with the correlation id.
`BCK.LEGAL_DOCS.0006`	400	business	—	No wallet linked to the authenticated Privy account	Link a wallet to the Privy account before retrying. Legal consent must be bound to an on-chain identity.

`BCK.METRIC`

Code	HTTP	Category	Retryable	Message	Hint
`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.
`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.
`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.
`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.
`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.

`BCK.METRICS`

Code	HTTP	Category	Retryable	Message	Hint
`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.

`BCK.NOTIF`

Code	HTTP	Category	Retryable	Message	Hint
`BCK.NOTIF.0001`	404	integration	—	Unable to find notification by id	Verify the notification id. The notification may have been deleted or never existed.
`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.
`BCK.NOTIF.0003`	500	integration	—	Error updating notification	Inspect the underlying error in logs. Notification update failed — usually a DB-layer error.
`BCK.NOTIF.0004`	500	integration	—	Error updating notification read status	Inspect the underlying error in logs. Notification read-status update failed — usually a DB-layer error.
`BCK.NOTIF.0005`	500	integration	—	Error deleting notification	Inspect the underlying error in logs. Notification deletion failed — usually a DB-layer error.
`BCK.NOTIF.0006`	404	integration	—	Error searching for notifications filtered by receiver	Verify the receiver address. Empty result sets surface as 404 by design.
`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.
`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.
`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.

`BCK.OAUTH`

Code	HTTP	Category	Retryable	Message	Hint
`BCK.OAUTH.0001`	404	auth	❌	OAuth resource not found	Verify the agentId or client identifier in the OAuth request.
`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.
`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.
`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.
`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.
`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.
`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.
`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).
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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`.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.

`BCK.OBSERVABILITY`

Code	HTTP	Category	Retryable	Message	Hint
`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.
`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.
`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.
`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.
`BCK.OBSERVABILITY.0005`	502	integration	—	Helicone API service unavailable	Inspect Helicone status page. The upstream Helicone API is unavailable; retry after a backoff.

`BCK.ORGANIZATIONS`

Code	HTTP	Category	Retryable	Message	Hint
`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).
`BCK.ORGANIZATIONS.0002`	500	business	—	Error getting organization members	Inspect the underlying error in logs. Members lookup failed — usually a DB-layer error.
`BCK.ORGANIZATIONS.0003`	500	business	—	Error saving organization branding	Inspect the underlying error in logs. Branding persistence failed — usually a storage-layer error for the uploaded logo, or a DB-layer error for the colour palette.
`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.
`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.
`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.
`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.
`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.
`BCK.ORGANIZATIONS.0009`	403	business	❌	User is not a member of the organization	Add the user as a member before performing membership-scoped operations.
`BCK.ORGANIZATIONS.0010`	500	business	—	Failed to update organization member	Inspect the underlying error in logs. Member-update failed — usually a DB-layer error.
`BCK.ORGANIZATIONS.0011`	404	business	❌	Organization not found	Verify the orgId. Soft-deleted organizations also surface as not-found.
`BCK.ORGANIZATIONS.0012`	500	business	—	Failed to deactivate organization	Inspect the underlying error in logs. Org deactivation failed — usually a DB-layer error.
`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.
`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.
`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.
`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.
`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.
`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.
`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.)
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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//customers//unblock) if this was in error.
`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.
`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.

`BCK.ORG_INTEGRATION`

Code	HTTP	Category	Retryable	Message	Hint
`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.
`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.

`BCK.ORG_WALLETS`

Code	HTTP	Category	Retryable	Message	Hint
`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.
`BCK.ORG_WALLETS.0002`	404	business	❌	Organization wallet not found	No organization wallet with this id exists for the specified organization.
`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.
`BCK.ORG_WALLETS.0004`	403	business	❌	Organization wallets are not available on this tier	Organization stablecoin wallets require a Premium or Enterprise organization.
`BCK.ORG_WALLETS.0005`	409	business	❌	Wallet is already shared with this group	This organization wallet already funds the group; nothing to add.
`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.
`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.
`BCK.ORG_WALLETS.0008`	409	business	❌	Cannot remove a wallet that still holds funds	Withdraw the wallet’s USDC/EURC balance to another address first, then remove it.
`BCK.ORG_WALLETS.0009`	422	validation	❌	Insufficient balance for the requested withdrawal	The withdrawal amount exceeds the wallet’s balance for that token.
`BCK.ORG_WALLETS.0010`	422	validation	❌	Invalid withdrawal destination address	The destination cannot be the zero address or the wallet’s own address. Provide a different recipient.

`BCK.PAYMENT_CREDENTIAL`

Code	HTTP	Category	Retryable	Message	Hint
`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.
`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.
`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.
`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.

`BCK.PAYPAL`

Code	HTTP	Category	Retryable	Message	Hint
`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.

`BCK.PLANS`

Code	HTTP	Category	Retryable	Message	Hint
`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.

`BCK.POINT`

Code	HTTP	Category	Retryable	Message	Hint
`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.
`BCK.POINT.0002`	404	business	—	User with id not found	Verify the user id. The user may have been deleted or never existed.
`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.
`BCK.POINT.0004`	404	business	—	Unable to search event points	Verify the event id. Empty per-event point lookups surface as 404.
`BCK.POINT.0005`	404	business	—	Unable to find user points aggregated	Verify the user id. Empty aggregated lookups surface as 404.
`BCK.POINT.0006`	404	business	—	Points rule not found	Verify the ruleId. Empty rule lookups surface as 404; rules may be disabled or removed.
`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.
`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.
`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.
`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.
`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.
`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).
`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.
`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.
`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.
`BCK.POINT.0016`	500	internal	❌	No crypto-seller points rule for the supplied price	getRuleIdByCryptoSellerPrice() saw a price the tier table does not cover.
`BCK.POINT.0017`	500	internal	❌	No crypto-buyer points rule for the supplied price	getRuleIdByCryptoBuyerPrice() saw a price the tier table does not cover.
`BCK.POINT.0018`	500	internal	❌	No fiat-seller points rule for the supplied price	getRuleIdByFiatSellerPrice() saw a price the tier table does not cover.
`BCK.POINT.0019`	500	internal	❌	No fiat-buyer points rule for the supplied price	getRuleIdByFiatBuyerPrice() saw a price the tier table does not cover.

`BCK.PROTOCOL`

Code	HTTP	Category	Retryable	Message	Hint
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`BCK.PROTOCOL.0011`	402	integration	—	Insufficient balance	Top up the buyer balance (USDC/EURC/USD/EUR depending on plan currency) before retrying. The protocol reverted because the order amount exceeds the wallet balance.
`BCK.PROTOCOL.0012`	500	integration	—	Error updating agent	Inspect the underlying error in logs. Agent metadata update reverted — verify the caller owns the agent and the new metadata is well-formed.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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).
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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).
`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).
`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.
`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/ confirms whether it exists (#2163).
`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).
`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).

`BCK.ROUTER`

Code	HTTP	Category	Retryable	Message	Hint
`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.
`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.
`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.
`BCK.ROUTER.0004`	404	business	❌	Router payment not found	No Router payment with that id belongs to the authenticated user.
`BCK.ROUTER.0005`	409	business	❌	Router payment is not in a settleable state	Only an Issued payment can be marked Settled. Re-reporting the same txHash on an already-Settled payment is a no-op; a different txHash, or a non-Issued state, is rejected.
`BCK.ROUTER.0006`	500	integration	✅	Error getting router payments summary	Transient server-side error building the payments summary; safe to retry. Inputs are validated upstream (invalid from/to return 400 BCK.ROUTER.0001, granularity is normalized), so this is not a bad-request issue.
`BCK.ROUTER.0007`	429	business	✅	Too many concurrent routed requests	You have too many in-flight mode-B routed requests (/route, /proxy) open at once. Let some complete before starting more, or slow the request rate.
`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.
`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.)

`BCK.STRIPE`

Code	HTTP	Category	Retryable	Message	Hint
`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.
`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.
`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.
`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.
`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.
`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.
`BCK.STRIPE.0007`	400	integration	—	Invalid input params	Verify the request body matches the endpoint schema. Common cause: missing planId or zero amount.
`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.
`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.
`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).
`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.
`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.
`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.
`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.
`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.
`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.
`BCK.STRIPE.0017`	400	integration	—	Invoices not found	Verify the Stripe subscription/customer reference. No invoices were found for the requested filters.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.

`BCK.STRIPE.CONNECT`

Code	HTTP	Category	Retryable	Message	Hint
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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).

`BCK.TRANSCODING`

Code	HTTP	Category	Retryable	Message	Hint
`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.
`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.
`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.
`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.

`BCK.TXS`

Code	HTTP	Category	Retryable	Message	Hint
`BCK.TXS.0001`	404	integration	—	Error searching asset transactions by id	Verify the asset/transaction id. Empty transaction lookups return 404 by design.
`BCK.TXS.0002`	404	integration	—	Error searching asset consumer transactions	Verify the consumer address and asset id. Empty result sets return 404 by design.
`BCK.TXS.0003`	404	integration	—	Error searching distintc asset transactions	Verify the asset id. Empty distinct-asset transaction lookups return 404.
`BCK.TXS.0004`	404	integration	—	Error searching plan transactions	Verify the planId. Empty plan-transaction lookups return 404 by design.
`BCK.TXS.0005`	404	integration	—	Error searching asset transactions grouped by owner	Verify the owner address. Empty owner-grouped transaction lookups return 404.
`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.
`BCK.TXS.0007`	404	integration	—	Error getting active users for owner	Verify the owner address. Empty active-users lookups return 404 by design.
`BCK.TXS.0008`	404	integration	—	Error getting total API calls for owner	Verify the owner address. Empty total-calls lookups return 404 by design.
`BCK.TXS.0009`	404	integration	—	Error getting total revenue for owner	Verify the owner address. Empty total-revenue lookups return 404 by design.
`BCK.TXS.0010`	404	integration	—	Error getting dashboard metrics for owner	Verify the owner address. Empty dashboard-metrics lookups return 404 by design.
`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.
`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.
`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.

`BCK.USER_PROFILE`

Code	HTTP	Category	Retryable	Message	Hint
`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).
`BCK.USER_PROFILE.0002`	404	business	❌	User profile not found	Verify the user identifier. The profile may have been disabled or never created.
`BCK.USER_PROFILE.0003`	400	validation	❌	No wallet linked to the authenticated Privy account	Complete wallet linkage in the Privy flow before calling endpoints that require a smart-account address (dashboards, profile reads, etc.).
`BCK.USER_PROFILE.0004`	400	business	❌	User profile already exists for this address	Use the PATCH endpoint to update an existing profile, or call POST with a different address. Profiles are unique per wallet.

`BCK.VERSION`

Code	HTTP	Category	Retryable	Message	Hint
`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.
`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.

`BCK.VGS`

Code	HTTP	Category	Retryable	Message	Hint
`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.
`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.
`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.
`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.
`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.

`BCK.VISA`

Code	HTTP	Category	Retryable	Message	Hint
`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.
`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.
`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.
`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.
`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.
`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`.
`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.
`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.
`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.
`BCK.VISA.0010`	404	integration	—	VGS webhook references unknown card	Verify the VGS payload references a card our DB has registered. Stale or cross-environment webhooks land here.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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).
`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.
`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//network-tokens) or minting a GA cryptogram (POST /cards//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).
`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.

Code	HTTP	Category	Retryable	Message	Hint
`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.
`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.
`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.
`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.
`BCK.WIDGET.0005`	500	business	—	Error deleting widget config	Inspect the underlying error in logs. Widget deletion failed — usually a DB-layer error.

`BCK.WIDGET_KEYS`

Code	HTTP	Category	Retryable	Message	Hint
`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.
`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.

`BCK.WIDGET_SESSION`

Code	HTTP	Category	Retryable	Message	Hint
`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.
`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.
`BCK.WIDGET_SESSION.0004`	500	auth	—	Error creating widget session user	Inspect the underlying error in logs. Widget guest-user creation failed — usually a DB-layer error.
`BCK.WIDGET_SESSION.0005`	401	auth	—	Invalid or expired widget session token	Re-issue the session token via the widget refresh endpoint. Session tokens are short-lived; expired tokens land here.
`BCK.WIDGET_SESSION.0008`	401	auth	—	Widget session token is missing required wallet claim	Reissue the session token after capturing the user wallet. Wallet-bound session features require the wallet claim.
`BCK.WIDGET_SESSION.0009`	401	auth	—	Widget session token is missing required apiKeyHash claim	Reissue the session token with the apiKeyHash claim populated. The widget runtime expects an apiKeyHash to attribute usage.
`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.
`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.
`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.
`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.
`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).
`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).
`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.

`BCK.X402`

Code	HTTP	Category	Retryable	Message	Hint
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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).
`BCK.X402.0016`	400	business	❌	Permission is already revoked	The permission was already revoked. No further action required.
`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.
`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.
`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.
`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.
`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`).
`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.
`BCK.X402.0023`	402	business	❌	Delegation budget insufficient for this order	The remaining delegation budget is smaller than the cost of this order. Use a smaller order, or create a new delegation with a higher `spendingLimitCents`.
`BCK.X402.0024`	402	business	❌	No active permission found for the delegation	The delegation has no active permission backing it. Re-create the delegation so its permission and session keys are provisioned.
`BCK.X402.0025`	402	business	❌	Permission has been revoked	The permission backing this token was revoked. Create a fresh delegation/permission and mint a new access token.
`BCK.X402.0026`	402	business	❌	Permission has expired	The permission backing this token expired. Create a fresh delegation/permission and mint a new access token.
`BCK.X402.0027`	402	business	❌	Payment method not found or unusable	No usable payment method was found for this request. Add or re-enable a payment method in the dashboard, then retry — optionally passing its identifier via `delegationConfig.providerPaymentMethodId` or `delegationConfig.cardId`.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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).
`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.
`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.
`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.
`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.
`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.

​Namespaces

​BCK.ACCOUNT_PROVISIONING

​BCK.AGENT

​BCK.APIKEY

​BCK.AUTH

​BCK.BILLING

​BCK.BRAINTREE

​BCK.BUDGETS

​BCK.CATALOG

​BCK.COMMON

​BCK.CREDITS

​BCK.DELEGATION

​BCK.ENTITLEMENTS

​BCK.GROUPS

​BCK.GUEST

​BCK.INVITATIONS

​BCK.LEGAL_DOCS

​BCK.METRIC

​BCK.METRICS

​BCK.NOTIF

​BCK.OAUTH

​BCK.OBSERVABILITY

​BCK.ORGANIZATIONS

​BCK.ORG_INTEGRATION

​BCK.ORG_WALLETS

​BCK.PAYMENT_CREDENTIAL

​BCK.PAYPAL

​BCK.PLANS

​BCK.POINT

​BCK.PROTOCOL

​BCK.ROUTER

​BCK.STRIPE

​BCK.STRIPE.CONNECT

​BCK.TRANSCODING

​BCK.TXS

​BCK.USER_PROFILE

​BCK.VERSION

​BCK.VGS

​BCK.VISA

​BCK.WIDGET

​BCK.WIDGET_KEYS

​BCK.WIDGET_SESSION

​BCK.X402

Namespaces

`BCK.ACCOUNT_PROVISIONING`

`BCK.AGENT`

`BCK.APIKEY`

`BCK.AUTH`

`BCK.BILLING`

`BCK.BRAINTREE`

`BCK.BUDGETS`

`BCK.CATALOG`

`BCK.COMMON`

`BCK.CREDITS`

`BCK.DELEGATION`

`BCK.ENTITLEMENTS`

`BCK.GROUPS`

`BCK.GUEST`

`BCK.INVITATIONS`

`BCK.LEGAL_DOCS`

`BCK.METRIC`

`BCK.METRICS`

`BCK.NOTIF`

`BCK.OAUTH`

`BCK.OBSERVABILITY`

`BCK.ORGANIZATIONS`

`BCK.ORG_INTEGRATION`

`BCK.ORG_WALLETS`

`BCK.PAYMENT_CREDENTIAL`

`BCK.PAYPAL`

`BCK.PLANS`

`BCK.POINT`

`BCK.PROTOCOL`

`BCK.ROUTER`

`BCK.STRIPE`

`BCK.STRIPE.CONNECT`

`BCK.TRANSCODING`

`BCK.TXS`

`BCK.USER_PROFILE`

`BCK.VERSION`

`BCK.VGS`

`BCK.VISA`

`BCK.WIDGET`

`BCK.WIDGET_KEYS`

`BCK.WIDGET_SESSION`

`BCK.X402`