Error codes

K-Block reports every problem with a stable, machine-readable code next to a human-readable message. Program against the code, never the message: messages may be reworded, codes do not change meaning.

You meet codes in four places:

• the Cloud API, which the dashboard and your scripts call;
• the Gateway, which answers agents, either at the HTTP level or as a refusal of one tool call;
• the client SDKs (@kblockai/client and the Python package kblock), which turn Gateway answers into typed errors and results;
• the dashboard, when it cannot get an answer from the Cloud API for your browser.

Use your browser's find function to look up a code. Related pages: Action statuses, Roles and permissions, Common problems.

How errors look

Cloud API errors

Every Cloud API error has the same JSON body and a matching HTTP status:

{
  "error": {
    "code": "FORBIDDEN",
    "message": "your role (viewer) does not allow this",
    "details": { "permission": "resources.write", "role": "viewer" }
  }
}

details is optional and depends on the code: for example issues for validation errors, required_scope for a management key without a scope, retry_after_seconds for rate limits. Every response carries an x-request-id header. When you contact K-Block support about a problem, give the code and this request ID. A 500 INTERNAL_ERROR contains no details of what failed; the request ID lets K-Block support find them. Some problems on K-Block's side have codes for K-Block's own diagnosis; see Server-side problems.

In the dashboard, an error box shows the message, guidance for codes it knows, then Code: and the request ID. For a problem on K-Block's side with a code for K-Block's own diagnosis, it shows a description in product terms instead of the code and the message, and the request ID when the answer has one (see Server-side problems and Dashboard codes).

Gateway answers

The Gateway answers in two ways:

• HTTP-level errors happen before any tool is looked at (wrong key, rate limit, Gateway unavailable). They are HTTP status codes with a JSON-RPC error body. See Gateway HTTP errors.
• Tool refusals are normal MCP tool results with isError: true. The K-Block part is in structuredContent.kblock:

{
  "isError": true,
  "structuredContent": {
    "kblock": {
      "status": "approval_pending",   // one of 11 refusal statuses
      "code": "APPROVAL_PENDING",     // the precise reason
      "detail": "the call requires approval; …",
      "protected_action_id": "<action-id>",      // when an action was recorded
      "approval_request_id": "<approval-id>",    // when there is one
      "expires_at": "…"                          // for pending and expired actions
    }
  }
}

Some refusals also carry retryable, and refusals of recorded decisions may carry a policy explanation (see What agents are told). See Gateway tool refusals.

Cloud API codes

Requests and sign-in

Permissions

Members and invitations

Names, state and concurrency

Identities, signatures and verification

Tools, MCP servers and discovery

Policies and rollout

See Activate, roll out and roll back and Observe and shadow.

Billing

When plans cannot be bought or managed here, GET /api/v1/orgs/<org-id>/billing reports configured: false, the Plan card on Billing says Billing is not configured in this environment (see When billing is not configured), and checkout and the customer portal answer 503 without Retry-After, a problem on K-Block's side (see Server-side problems). If you need a paid plan, contact K-Block support with the request ID.

Server-side problems

A 5xx answer with a code this page does not list, and a 503 without Retry-After, mean a problem on K-Block's side that you cannot fix. Examples: K-Block cannot send e-mail right now, plans cannot be bought or managed here, a stored receipt bundle is missing or does not match its recorded hash, or a stored secret of your organization cannot be read. The codes of these answers are for K-Block's own diagnosis. Retry later; if it keeps happening, contact K-Block support with the request ID from the X-Request-Id response header. GET /api/v1/gateway/identity answers 404 when no Gateway identity is registered yet. That is also a problem on K-Block's side: contact K-Block support with the request ID.

• If rejecting an approval request or cancelling an action fails because K-Block could not store its receipt bundle, nothing was recorded. Try again later.
• A webhook delivery whose endpoint's signing secret cannot be read fails, and its error says that the signing secret cannot be decrypted. Rotate secret on the endpoint stores a new signing secret.
• An MCP server's authorization header that cannot be read is reported as UPSTREAM_CREDENTIAL_INVALID instead (see Tools, MCP servers and discovery).

The dashboard shows an answer whose code is for K-Block's own diagnosis without its code and message, as one of these messages:

• "K-Block cannot send e-mail right now, so no message was sent."
• "Plans cannot be bought or managed here right now."
• "K-Block could not complete this request because of a problem on its side." (for stored secrets, receipt storage and the Gateway identity)

It adds "If this keeps happening, contact K-Block support and give them the request ID below." and the request ID.

Gateway HTTP errors

These answers come before any tool is looked at, so nothing is recorded or executed.

Gateway tool refusals

A refusal's status is one of these eleven values. Its code gives the precise reason. The answers of POST /v1/authorize use the same statuses and codes.

The dashboard explains many of these codes on the action page. See Gateway and tools for diagnosis.

Client SDK errors

The client SDKs return Gateway decisions as results (a completed call or a refusal with the status and code above). They throw errors only for transport problems and for answers that are not K-Block results. @kblockai/client and the Python package kblock use the same class names and codes; Python spells the attributes in snake case (retry_after_seconds, outcome_unknown).

All of them extend KBlockError, which has a code property. See the TypeScript client and Python.

Dashboard codes

When the dashboard cannot reach the K-Block service for your browser, or K-Block does not answer within 60 seconds, the dashboard shows "The dashboard could not reach the K-Block service. Try again in a moment." followed by "If this keeps happening, contact K-Block support and tell them when it happened." It shows no code, and there is no request ID. Nothing you entered was wrong, and nothing in your browser needs fixing. Reload the page and try again. If you were saving a change, check whether it was saved before you repeat it. If the problem continues, contact K-Block support and tell them when it happened.

If the dashboard is asked for an API path it cannot use, it shows "K-Block could not complete this request because of a problem on its side." with the same advice to tell K-Block support when it happened, and no request ID. Reload the page.

The browser part of the dashboard adds a few codes of its own when no usable answer arrives:

• NETWORK_ERROR: your browser got no answer from the dashboard. Check your connection and reload the page.
• ABORTED: the request was cancelled.
• INVALID_RESPONSE: the answer could not be read.
• HTTP_<status>: an error answer that is not in the K-Block format.

For INVALID_RESPONSE and HTTP_<status>, reload the page; if the problem continues, contact K-Block support with the code and the time it happened.

The dashboard also refuses to submit a change for the wrong account. SESSION_CHANGED (409) means that the account signed in to this browser changed, in another tab or window, after this page prepared the change. The change is not carried out for that account, and nothing is recorded, not even an object you already signed. The message says "The account signed in to this browser changed (in another tab or window), so this was not done and nothing was recorded. The page now shows the account that is signed in: to act as the previous account, sign in to it again; otherwise check the page, then try again." See Your account.