> For the complete documentation index, see [llms.txt](https://docs.kinesis.network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kinesis.network/api/errors.md).

# Errors and recovery

Interpret errors, recover safely and provide useful diagnostics to support.

REST failures return a JSON error envelope. MCP tool failures put an error envelope in `structuredContent` and set `isError: true`; their request-ID behavior differs as described below. Authentication and rate limiting can fail before MCP runs a tool.

```json
{
  "error": {
    "code": "insufficient_scope",
    "message": "The credential lacks a required permission",
    "requestId": "<request-id>",
    "requiredScopes": ["apps:write"]
  }
}
```

This is an illustrative **REST** error. REST errors always include `requestId`. MCP tool errors include it only for server-side failures (status 500 or above); client errors such as `invalid_request`, `insufficient_scope` and `forbidden` omit it. The HTTP `X-Request-Id` header is unchanged, including failures before tool execution. Branch on `code`, and retain a request ID when one is present.

## Fix the request or access

| Code                     | Recovery                                                                              |
| ------------------------ | ------------------------------------------------------------------------------------- |
| `invalid_request`        | Inspect `issues` for field paths and validation messages                              |
| `payload_too_large`      | Reduce the request body below the reported byte limit                                 |
| `unauthorized`           | Check the bearer credential, expiry and revocation                                    |
| `insufficient_scope`     | Add the scopes listed in `requiredScopes`, or reauthorize MCP                         |
| `key_project_restricted` | Use a permitted project; project-limited keys cannot run organization-wide operations |
| `org_required`           | Pass an organization slug from `error.details.orgs` as REST `?org=` or MCP `org`      |
| `forbidden`              | The user's role cannot perform this action                                            |
| `not_found`              | Verify the identifier and the user's access to the resource                           |

In compact MCP mode, action argument errors use paths such as `params.projectId`. A failure against the action's input schema includes `action` and the full `inputSchema`; operation-level checks may return only the issues. Use `describe_action` to inspect selected actions before constructing complex arguments.

## Fix deployment state

| Code                                                     | Recovery                                                                                                     |
| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `app_running`                                            | Stop the app and wait before deleting                                                                        |
| `project_has_running_apps`                               | Stop the apps listed in `appIds` before deleting the project                                                 |
| `no_suitable_machines`                                   | Review hardware and placement; widen constraints where appropriate                                           |
| `grid_quota_exceeded`                                    | Free the creator’s quota, lower minimum instances or ask an organization admin                               |
| `serverless_disabled`                                    | Target an accessible grid or ask an organization admin; existing running apps are not stopped by the setting |
| `serverless_gpu_unavailable`                             | GPU apps require a grid; supply `config.grids.ids` or remove the GPU requirement                             |
| `build_in_progress`                                      | Wait for the active build to finish before rollback                                                          |
| `build_not_deployable`                                   | The app has never deployed or the build has no usable stored image; build the commit again                   |
| `grid_to_serverless`                                     | This conversion is unsupported; create a separate app if needed                                              |
| `app_source_unsupported`                                 | Manage this source through its supported portal flow                                                         |
| `app_config_unavailable`                                 | The `envFrom` source app has no configuration available to copy; inspect it before retrying                  |
| `app_not_on_grid`                                        | Confirm the runtime `appGuid` belongs to the grid before using grid app controls                             |
| `domain_not_verified`                                    | Create the returned DNS record and wait for propagation before retrying                                      |
| `github_installation_not_found`, `github_repo_not_found` | Check the connected GitHub installation and repository access                                                |
| `github_branch_not_found`, `github_commit_not_found`     | Browse the available branch or commit before retrying                                                        |
| `github_path_not_found`, `github_file_too_large`         | Check the repository path or select a smaller file for the contents API                                      |
| `github_not_configured`                                  | Repository deployment is not enabled on that deployment                                                      |
| `provision_order_failed`, `provision_quota`              | Inspect the order and the message before retrying or changing capacity                                       |

## Resolve account and payment issues

| Code                                                          | Recovery                                                                                                    |
| ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `insufficient_balance`, `balance_over_limit`                  | Inspect the balance and returned `billingUrl` or `topUpNeededCents`; `billingUrl` is an absolute portal URL |
| `no_payment_method`                                           | Add a payment method through the portal                                                                     |
| `card_declined`, `authentication_required`, `blocked_by_risk` | Resolve the payment issue in the portal; repeated charges are not a fix                                     |
| `amount_too_large`, `topup_limit`                             | Check the organization’s transaction cap or reset time                                                      |
| `app_creation_quota_exceeded`                                 | Check the organization’s app-creation allowance                                                             |
| `first_payment_in_dashboard`                                  | Complete the first payment through the portal before using saved-card top-ups                               |
| `voucher_not_found`, `voucher_rejected`                       | Check the code and the returned eligibility or redemption message                                           |
| `too_many_attempts`                                           | Pause repeated voucher attempts and follow the response before trying again                                 |
| `account_frozen`                                              | The person is frozen across organizations; contact support                                                  |
| `org_frozen`                                                  | The organization cannot spend or pay; an admin contacts support                                             |

REST may return `billingUrl` and payment diagnostics. MCP removes `billingUrl` and phrases balance failures as entitlement limits; explain the refusal and leave billing to an organization admin. MCP has no credit-purchase or auto-reload-setting action.

## Organization and member changes

| Code                            | Recovery                                                                   |
| ------------------------------- | -------------------------------------------------------------------------- |
| `owner`, `last_admin`           | Transfer ownership or retain another admin before changing membership      |
| `role_changed`, `owner_changed` | Read current members again before proposing another change                 |
| `invites_admins_only`           | An admin must invite, or enable developer invitations                      |
| `role_too_high`                 | Invite at your own organization role or below                              |
| `already_member`                | Add the existing member to the resource instead of inviting again          |
| `invitation_exists`             | An admin can resend another member’s pending invitation                    |
| `resend_too_soon`               | Wait at least a minute before resending to that address                    |
| `invitation_limit`              | Review pending invitations; the limit is 100                               |
| `invitation_closed`             | The invitation expired, was answered or was withdrawn; request a fresh one |
| `org_limit_reached`             | The person already owns five organizations                                 |
| `invalid_slug`, `slug_taken`    | Choose an available URL-safe slug                                          |

Organization- or project-limited credentials cannot create an organization or answer its invitations. Re-approve older OAuth connections for new scopes when needed. Old resource invitation cancellation differs from organization invitation revocation: cancelling an accepted resource invitation revokes its grant.

SSO errors such as `sso_required` during browser credential setup and `sso_session_needed` when enabling the requirement belong to portal sign-in/setup flows. They do not mean existing public API keys need a browser SSO session. See [SSO troubleshooting](/organizations/single-sign-on.md).

## Retry only when useful

| Code                                                        | Retry behavior                                                      |
| ----------------------------------------------------------- | ------------------------------------------------------------------- |
| `rate_limited`                                              | Wait for `Retry-After` or the reported reset time                   |
| `request_in_progress`                                       | Wait for `retryAfterSec`, then repeat with the same idempotency key |
| `idempotency_conflict`                                      | Do not replay changed arguments; use a new key for a new action     |
| `invalid_idempotency_key`                                   | Correct the key's length or format                                  |
| `topup_in_progress`                                         | Inspect the payment state and retain the payment's idempotency key  |
| `upstream_unavailable`, `upstream_github`, `internal_error` | Retry with backoff only when repeating the operation is safe        |

For creates and provisioning, follow the [idempotency rules](/api/conventions.md). For a restart, build trigger or other non-idempotent action, inspect current state before retrying after a lost response.

The endpoint reference lists additional operation-specific errors. If a problem persists, send [support](/support.md) the code, request ID when available, resource ID and approximate time, with credentials and secrets removed.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.kinesis.network/api/errors.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.