Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.nevermined.app/llms.txt

Use this file to discover all available pages before exploring further.

Every error response from the Nevermined API follows a single, stable shape so your code can branch on code, surface a friendly message to the user, and link directly to the docs entry that explains the failure.
Locked fields — code, message, and the HTTP status — are guaranteed for every error response. Additive fields (hint, docsUrl, category, retryable, correlationId) only appear when the catalogue or the throw site supplies them. Consumers that branch only on code and message ignore the rest transparently.

​
Response shape

{
  // Locked — always present. SDKs read these.
  "code": "BCK.X402.0008",
  "message": "Failed to order crypto plan",

  // Additive — present when the catalogue or the throw site supplies them.
  "details": "Bundler returned execution-reverted",
  "hint": "Verify the wallet has sufficient balance and that the plan is active. Inspect params.planId and the bundler RPC logs around the request correlationId.",
  "docsUrl": "https://docs.nevermined.ai/docs/development-guide/api-errors/codes#bck-x402-0008",
  "category": "integration",
  "retryable": true,
  "correlationId": "a3f6b1c4-7d2e-4a9b-8e0c-12f4d8e6c5b9",
  "uuid": "e-550e8400-e29b-41d4-a716-446655440000",
  "date": "2026-05-09T12:34:56.789Z",

  // JSON-stringified contextual params from the throw site (parse with JSON.parse if needed).
  "params": "{\"planId\":\"43298432984329\"}"

  // Server stack — only emitted when NODE_ENV is "development" or "test".
  // "stackTrace": "..."
}

​
Field reference

code

Stable identifier of the form BCK.<NAMESPACE>.<NNNN>. Branch on this in your error handlers — it never changes for a given failure mode.

message

Human-readable canonical reason. Safe to surface to end users; it never includes secrets.

hint

Actionable remediation. Tells you what to fix or where to look. Optional — present when the catalogue or throw site supplies one.

docsUrl

Permalink to the entry on this docs site. Surface as a “Learn more” link in your UI.

category

One of validation, auth, business, integration, internal. Useful for client-side fallback strategies without parsing the message.

retryable

true when the same call is expected to succeed after a backoff. Absent when the catalogue does not assert either way.

correlationId

Request-scoped id stamped by the global filter and echoed in the x-correlation-id response header. Quote this when reporting issues.

params

JSON-stringified contextual data from the throw site (IDs, state). Always a string in the wire format — parse with JSON.parse if you need structured access. Never includes credentials or PII.

details

Free-form technical reason supplied at the throw site (e.g. "Bundler returned execution-reverted"). Supplements — never replaces — the canonical message. Optional.

uuid

Server-generated exception id of the form e-<uuid>. Distinct from correlationId; use it when correlating a specific failure event with server logs. Optional.

date

ISO-8601 timestamp the API stamped when the exception was constructed. Always present.

stackTrace

Server-side stack trace. Emitted only when NODE_ENV is development or test — never in staging or production. Do not depend on it from client code.

​
Reading errors from the SDK

Both first-party SDKs surface the API’s code and message directly, so you can branch on the code in your application. 
import { Payments, PaymentsError } from '@nevermined-io/payments'

const payments = Payments.getInstance({
  nvmApiKey: process.env.NVM_API_KEY!,
  environment: 'sandbox',
})

try {
  await payments.plans.orderPlan(planId)
} catch (err) {
  if (err instanceof PaymentsError) {
    // err.code === 'BCK.X402.0008'
    // err.message === 'Failed to order crypto plan. <backend message>'
    if (err.code === 'BCK.X402.0008') {
      showRetryableError(err.message)
    } else {
      throw err
    }
  }
}

​
Correlation ids

Every request gets a unique correlationId:
  • If you send x-correlation-id (or x-request-id) on the request, the API honours it.
  • Otherwise the API generates a fresh UUID.
  • Either way, the id is echoed back in the x-correlation-id response header and stamped into the JSON body of any error response.
When you open a support ticket or file a bug, quote the correlationId — it lets us pull the matching server logs without you sharing the request payload.

​
Categories at a glance

validation

Caller’s request did not pass schema or shape validation. Fix the request and retry. Not retryable as-is.

auth

Caller is unauthenticated, the credentials are invalid, or the caller lacks the required role. Fix credentials or membership and retry.

business

Caller’s request is well-formed and authenticated, but a business rule blocks it (e.g. user already a member, plan already deactivated, points cap exhausted). Adjust the request semantics.

integration

The API hit an upstream system that misbehaved (Stripe, Braintree, the blockchain RPC, the bundler). Often retryable: true. Backoff and retry.

internal

A bug or invariant violation on our side. Quote the correlationId in a support ticket — these need engineering attention.

​
Full code catalogue

The complete list of every code, its HTTP status, category, message, and remediation hint lives in the API Errors → Codes page under the API tab.

See every error code

Browse all BCK.* codes — anchored by code so you can deep-link to a specific failure mode (#bck-x402-0008).
A handful of catalogue entries return an HTTP 2xx status because they describe informational no-op outcomes rather than failures — for example BCK.PROTOCOL.0018 (“agent already in the desired state”) and BCK.PROTOCOL.0019 (“plan already in the desired state”) are emitted with 200 OK when a toggle endpoint is called against state that already matches the request. The shape is identical to the error responses described above, so the same SDK handlers and docsUrl deep-links continue to work; consumers that branch on code can treat these as “already done, nothing to do”.
This page is reachable from three places in the sidebar so you can find it from wherever you’re working:
  • API → API Errors — the canonical home, alongside the endpoint reference.
  • Guides → API Errors — for readers exploring concepts.
  • SDK → TypeScript SDK / Python SDK / CLI / OpenClaw Plugin — at the bottom of each SDK group, since SDK consumers see these errors most often.