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.

{
  "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
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.

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. 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 the code, request ID when available, resource ID and approximate time, with credentials and secrets removed.