Error codes

The codes on this page mean the same whichever module answers with them. The body's module names the module that answered; the code is documented here, under the platform's core. The body itself is described in Errors.

Unless an entry says otherwise, the body has the fields error, code, module and correlationId, and a 5xx from a module reaches you with error replaced — see Errors from the gateway.

Requests the platform cannot accept

MODEL_BINDING_FAILED

Status 400, on any route.

The request could not be read: the body is not valid JSON, a value has the wrong type, or a required parameter is missing. error is the fixed sentence "Request failed with status 400. Check request format and parameters." and does not say which part was wrong.

What to do: check the request against the route's format — the JSON, the types of its values and the parameters in the path and query.

BAD_REQUEST

Status 400, on any route. A few routes use it with 413 or 415 when the request body itself cannot be read.

The request is malformed, or refers to something that is not valid; error says what. Some routes also answer a failed validation with this code and the field errors in errors — see Validation errors. Some failures inside the platform are reported this way as well.

What to do: correct what error names. When it describes nothing you can change in the request, report it with the correlationId.

VALIDATION_FAILED

Status 422, on any route that validates its input. The core's route for the telemetry settings answers it with 400.

The request is well-formed but its values fail validation. When the fields are known, details lists them, one { "field": "…", "message": "…" } per failure, and error is "Validation failed."; otherwise error gives the reason and there are no details. A 422 whose body names no other code also carries this code; error then says what was refused.

What to do: correct the named fields and send the request again.

UNAUTHORIZED

Status 401, on any route that needs a sign-in.

The request carried no token, or one that is invalid or has expired. For a module's routes the core answers with "error": "missing bearer token" in all three cases. The MCP interface answers with a WWW-Authenticate: Bearer resource_metadata="…" header that tells an AI client where to sign in.

What to do: get a new token and send it as Authorization: Bearer <token> — see Authenticate.

NOT_FOUND

Status 404, on any route.

No route matches the path, or the resource, resource group or other object it names does not exist.

What to do: check the path and the names in it, including the resource group.

METHOD_NOT_ALLOWED

Status 405, on any route.

The route exists but does not accept this HTTP method.

What to do: use a method the route accepts. https://api.example.com/api/routes lists them — see List the routes.

Permissions

FORBIDDEN

Status 403, on any route that checks a permission.

You are signed in but do not hold the action the route needs at the scope in its path. error does not name the missing action.

A module that cannot reach the platform's authorization service may answer FORBIDDEN too, because it refuses a request it cannot check; other modules answer AUTHORIZATION_UNAVAILABLE in that case.

What to do: find the role that grants the action on the module's permissions page, and ask an owner of the boundary for it — or request it as just-in-time access, see Request access. If you already hold the role, try again shortly.

FORBIDDEN_REQUESTABLE

Status 403. Returned when you delete a container instance (DELETE /boundaries/{boundaryId}/resourcegroups/{resourceGroupName}/resources/containerinstances/{name}) but may not delete the vault that is deleted with it. Nothing is deleted.

The platform files a just-in-time request for Contributor on the vault on your behalf. details describes it: Action, Scope, Subject (the vault), RoleDefinitionId, RoleName, Justification, and — when a request could be filed — JitRequestId and JitStatus.

What to do: have an owner approve the request, activate it, and delete again — see Activate. Without a JitRequestId, request the role in RoleName at Scope yourself.

VAULT_GRANT_FORBIDDEN

Status 403. Returned when you create or change a container instance, or deploy a blueprint that creates one, whose containers read secrets from a vault on which you may not assign roles. Nothing is created or changed.

The instance's identity needs Secrets Reader on the vault, and only an owner of the vault can grant it. The platform files a just-in-time request for Owner on the vault on your behalf, or reuses one you already have. details describes it: Vault, ResourceGroup, Scope, PrincipalId (the instance's identity, when it has one yet), and — when a request could be filed — JitRequestId and JitStatus.

What to do: have an owner approve the request, activate it, and deploy again — see Activate. Without a JitRequestId, request Owner on the vault yourself.

AUTHORIZATION_UNAVAILABLE

Status 503. Returned by some platform modules, on any of their routes that checks a permission.

The module could not reach the platform's authorization service to check your permission, so it refused the request rather than let it through unchecked. Other modules report the same situation as FORBIDDEN.

What to do: retry shortly. If it persists, report it with the correlationId.

Conflicts

CONFLICT

Status 409, on routes that change something.

The request conflicts with the current state, and error says how: the resource was changed by someone else at the same time, a boundary still holds resources, a platform rollout is already running or cannot be cancelled, paused or rolled back in its current state, and more. A 409 whose body names no other code also carries this code.

What to do: read error, wait for or resolve the state it describes, and try again. A concurrent change needs nothing more than a retry.

DUPLICATE

Status 409, on routes that create something with a name: a resource group, an app, a static web app, an S3 account, a blueprint instance and others.

Something with that name already exists where you are creating it. error names it, or reads "A resource with the same name already exists."

What to do: choose another name, or work with the existing one.

Compute plans

A boundary's policies can restrict which compute plans its resources may use. Apps, PostgreSQL clusters, SQL Server instances, Qdrant clusters and container instances check the policy when they are created, when their compute plan is changed, and — for a container instance — when a revision is rolled back.

compute_plan_not_allowed

Status 422, on the create and update routes of the resources above.

A boundary policy does not allow the requested compute plan for this resource type. error names the plan, and the component for a container instance, and lists the plans the policy allows, or says that it allows none. The list is only in that sentence; there is no separate field for it.

What to do: choose one of the listed plans, or ask whoever manages the boundary's policies to allow the plan.

compute_plan_policy_unavailable

Status 503, on the same routes.

The platform could not read the boundary's compute plan policy, so it refused the change rather than risk one the policy forbids. error reads "The boundary's compute plan policy could not be checked, so the request was refused. Try again shortly." when it reaches you; through the gateway it is replaced as for any 5xx.

What to do: retry shortly. If it persists, report it with the correlationId.

Failures inside the platform

PLATFORM_ERROR

Status from 400 to 599, on routes that read or change resources in Kubernetes.

The platform asked Kubernetes to create, change, read or delete a resource, and it failed. error reads "Failed to {operation} {type} '{name}': {reason}". When Kubernetes refused a create or change, the status is the one it gave — for example 409, 422 or 403. Otherwise the status follows the reason: 403 for forbidden, 401 for unauthorized, 404 for not found, 409 for already exists, and 502 for anything else.

What to do: for a 4xx, correct what the reason names. For a 502, retry; if it persists, report it with the correlationId.

GRPC_ERROR

Status 404, 403, 401, 400, 409, 429 or 503 when the service's answer maps to one, otherwise 502. On any route that calls another platform service.

A call from the module to another platform service failed. error reads "Upstream service error: …" with the service's reason.

What to do: for 503 or 502, retry shortly. For the other statuses, act on the status: check the names, your permission or the request.

INTERNAL_ERROR

Status 500, on any route.

An unexpected error. error is "An internal error occurred." or the module's own description, and through the gateway it is replaced as for any 5xx. A 500 whose body names no other code also carries this code.

What to do: retry once; if it fails again, report it with the correlationId.

NOT_SUPPORTED

Status 501, on any route.

The operation is not supported, here or in this form. error is "This operation is not supported."

What to do: do not retry; the answer will not change.

REQUEST_FAILED

Status any error status without a more specific code — for example 409, 410, 422, 429, 500 or 503 when the route gave no further detail. On any route.

The route answered with an error status and no body — or, at a status such as 410, 429 or 503 that has no code of its own, with a body that names no code. error is "Request failed with status {status}." or the route's own sentence.

What to do: act on the status. For 429 and 503, retry after a while; for others, report it with the correlationId if the status does not explain it.

Errors from the platform's core

MODULE_UNAVAILABLE

Status 503, with "module": "kernel". On the routes of a module, which the core forwards to it.

The core could not hand the request to the module that serves the route:

• The module is not running. It is not registered, or has stopped reporting that it is alive. error reads "The '{name}' module is not available right now (no active registration). Retry shortly." Only routes under …/resources/{type} are recognised while their module is down; the other routes of a module that is not running answer as if they did not exist, usually with NOT_FOUND.
• The module did not respond. The connection failed, or the module took too long to answer. error reads "The '{name}' module did not respond (…). Retry shortly."

targetModule names the module: in the first case the resource type from the path, such as postgresclusters, or unknown; in the second the module's registration name, such as postgres. Neither is the documentation key that module carries elsewhere.

What to do: retry shortly. If it persists, report it to your platform administrator with the targetModule and the correlationId.

mcp_disabled

Status 404, with "module": "kernel". On the MCP interface, https://api.example.com/mcp, and its discovery document under /.well-known/oauth-protected-resource, with or without a sign-in.

The platform's MCP interface for AI clients is turned off. error reads "The MCP interface is not enabled on this platform. A Platform Owner turns it on under Platform settings."

What to do: ask a platform administrator to turn the interface on — see Turn on AI clients. Once it is on, connect again as described in Connect an AI client.