Source: schemas/wire_errors.json #
Generated automatically from the published contract sources.
Source path: schemas/wire_errors.json.
Complete source #
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "tzCloud — refusal names, contract version 1",
"version": "2026-11-21.4",
"description": "Every refusal name a surface of the platform uses (MAPI-15 in the management API contract), listed once with its surfaces, the HTTP status where one status is fixed across every site (null where it varies or the name is recorded rather than sent), the statement owning the behaviour (null where no statement covers it), and a one-clause summary. The list is pinned by a test in the platform's suite against the source: a name the source uses and this list lacks, or a name this list carries and the source no longer uses, fails that suite. The JSON refusal bodies of the management action surface follow wire_error.schema.json, and the body another surface sends under a name of this list is stated by that surface's owning statement, in the shape that surface sends (MAPI-15). A row's members, where it carries them, state the members the refusal's body carries on the management action surface beyond the six base members of wire_error.schema.json, each typed and described by a schema fragment, and state nothing of another surface's body under the same name. This inventory also includes standard OAuth error parameters in WWW-Authenticate challenge headers and authorization redirects, whose protocol shapes remain their own.",
"surfaces": {
"management_action": "An action of schemas/management_api.json, on its HTTP route and through the MCP tool that surfaces it (MAPI-08); a refusal recorded on a pending action is read through read_approval_status.",
"mcp_server": "The MCP transport’s refusals for protected tool calls and resource reads, and the tool dispatch surface.",
"storage": "The object storage surface under /storage/v0 (OST-L0-01 through OST-L0-08).",
"egress": "The egress gateway under /egress/v0 (EGW-L0-01 through EGW-L0-09, and EGW-L0-18 for the day limit).",
"realm_surface": "The accounts service: the end-user sign-in, passkey, session, and deletion routes on the application hostname (ACS-L0-01 through ACS-L0-10), the platform-origin callback pages, and the verification route /accounts/v0/verify (ACS-L0-06).",
"builder_sign_in": "The builder realm on the control plane: the OAuth authorization-server routes (MCP-02), the builder passkey routes (ACS-L0-10), the linking and interrupt routes (ACB-L0-03), and the invitation redemption route (ACS-L0-08; ACB-L0-77). It also includes the tzMesh site token route /accounts/v0/tzmesh/site-token (ACS-L0-18).",
"router": "The serving router on the application hostnames and their custom domains (SVC-L0-07; SVC-L0-25) and the two platform-internal resolve endpoints it reads, resolve and resolve_host.",
"egress_tunnel": "The egress tunnel seat in the hosting cell — the HTTP CONNECT proxy of the tunnel mode (EGW-L0-11; EGW-L0-16). A refusal is a 403, or 429 at one of the application's egress limits, with 407 for the credential, 502 for a failed dial, and 503 for an unanswered declaration read. The X-Egress-Refusal header gives its name and the body is { contract_version, error, detail, host, port }; egress_undeclared's carries its remedy beside them and a limit's the count, the limit, and the reset (EGW-L0-14; EGW-L0-18). Every refusal is also a row of the seat's establishment record (EGW-L0-14).",
"logging": "The logging ingest under /logging/v0 (the logging package's wire statement; read through read_logs and read_counters).",
"harness": "The runtime harness inside every application container — the inbound guard (HST-L0-01; SVC-L0-07 as amended) and the bounded execution window's abort half (HST-L0-03). The abort half's two records, `window_ended` and `process_ended`, are written to the container's console log rather than sent on the wire. The source is Node.js Runtime's boot module, which the pin test reads beside the platform's own source.",
"documentation": "The authenticated machine files of the documentation trees (PLD-L0-69), a gated tree serving a connection whose account holds the tree; MCP documentation reads use the mcp_server surface.",
"push": "The push service's send route under /push/v0, taken under the platform credential alone.",
"email": "The email service's send route under /email/v0, taken under the platform credential alone.",
"deploy_progress": "The deploy command's progress read: the read the turnzero command makes under the upload grant its preparing `deploy` call returned, from that grant's start until five minutes after the deploy ends, never past fifteen minutes after the start (PLD-L0-86). It returns plain text lines, and a refusal is a JSON body of `contract_version`, `error`, and `detail`.",
"workflow_start": "The platform's own start-line route, which Turn Zero's scheduled hosted workflows call to record that a run started, presenting the run's identity token from GitHub, and which no customer calls (PLD-L0-76). A refusal is a JSON body of `contract_version`, `error`, and `detail`.",
"support_read": "The support account read and the Questions page's chat under /api/v1/support/ (MAPI-29). It covers the website's chat ids, a signed-in visitor's consent and its end under the support cookie, the support agent's read of the shared account under the support read token, and the chat's message stream and turn read. Each is a same-origin JSON post from the page. The support cookie is read where the browser holds one, and the bot check applies to a signed-out chat's message on an estate that sets a bot check.",
"account_mail": "The platform's own account mail route, which the issue service alone may call to email an account at its verified addresses, and which no customer calls (EML-L0-10). A refusal's body holds at least `contract_version`, `error`, and `detail`.",
"dashboard_picture": "The signed-in account's picture read at GET /dashboard/account-picture (WEB-L0-27). Ordinary refusals carry JSON error and detail. Admission's rate_capped also carries contract_version: 1. A thrown error returns a 500 HTML failure page, outside this catalogue's refusals.",
"payment_event": "The payment provider's event delivery at POST /api/v1/payment-events. It needs no session; the platform verifies the provider's signature over the raw request bytes."
},
"refusals": [
{
"name": "access_denied",
"surfaces": [
"builder_sign_in",
"management_action"
],
"status": null,
"owner": null,
"summary": "You declined at the identity provider or cancelled on the page that asks to allow a tool, the builder's line, or the device verification page. No token was minted.\n\nA sign-in for a product or resource your account cannot access also receives this refusal, with no description. The authorization-code flow returns it on the client redirect as error=access_denied (302), and the device-code grant at the token endpoint (400). A product site's token route also refuses such an account with this name (403), and mints no token (ACS-L0-18).\n\nA page-only account picture action is also refused with 403 where the account cannot access the product that holds the picture. The relay makes no call to that product under the refused mint (ACS-L0-25).",
"remedy": "Start the sign-in again from your tool, and accept at the identity provider or allow on the page. For a product or resource that restricts access, use an account with access. For an account picture, use an account that has access to the product that holds the picture."
},
{
"name": "access_link_account_limited",
"surfaces": [
"management_action"
],
"status": 403,
"owner": "ACB-L0-87",
"summary": "You called invite_end_user with email from an access-link account: a test account Turn Zero set up with a sign-in link for one person who has no account of their own. Such an account invites no one into a realm, so nothing is issued and no message is sent.",
"remedy": "Nothing you do corrects this: an access-link account invites no one. Its other actions work as they do for any synthetic account."
},
{
"name": "account_application_limit",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "PRC-L0-16",
"summary": "The account holds as many live applications as its limit allows; nothing was created.",
"remedy": "Ask the account's owner what to do. Read `list_applications` to see what the account holds."
},
{
"name": "account_credential_required",
"surfaces": [
"management_action"
],
"status": 403,
"owner": "PLD-L0-47",
"summary": "You called halt_environment on production with a minted token bounded to one application. Stopping production is an account action. Only the account's session or a token minted for the whole account can do it, so that a leaked application-bounded token cannot stop production. The bounded token still works for halt_environment with resume: true on either environment and for halting development.",
"remedy": "Repeat halt_environment on production under your account's session, or under a token minted with mint_token for the whole account.",
"members": {
"scope": {
"type": "object",
"description": "The bound of the token presented: a token minted for one application, under which halting production is refused.",
"properties": {
"kind": {
"type": "string",
"description": "The kind of bound, always application here."
},
"application": {
"type": "string",
"description": "The id of the application the token is bounded to."
}
}
}
}
},
{
"name": "account_mail_production_only",
"surfaces": [
"account_mail"
],
"status": 403,
"owner": "EML-L0-10",
"summary": "The issue service's development environment asked the account mail route to send. That route serves a production credential alone, so nothing was sent.",
"remedy": "Nothing you do corrects this. The route serves a production credential alone."
},
{
"name": "account_not_synthetic",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "MAPI-16",
"summary": "A staff call on synthetic accounts, a purge or a read of a sign-in code or of an account's state, gave an account that exists and is not synthetic. The purge refuses as a whole and deletes nothing, because a customer's account is deleted only through delete_account and its browser approval (API-L0-07). The two reads return nothing of a customer's sign-in or state. The refusal lists the accounts. Under the synthetic_seed_purge grant, a purge refuses such an account with account_outside_batches instead, because it checks your reach first. Under synthetic_estate, the two reads do the same.",
"remedy": "Remove the accounts the refusal lists from your request, then repeat. To delete a customer's account, call delete_account and give its browser approval.",
"members": {
"accounts": {
"type": "array",
"items": {
"type": "string"
},
"description": "The account ids the request gave that exist and are not synthetic, as you wrote them. The list is never empty."
}
}
},
{
"name": "account_outside_batches",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "MAPI-16",
"summary": "Under a synthetic grant, you gave the purge, the sign-in code read, the setup mail read, or the state read a synthetic account outside your reach. Under synthetic_estate, your reach is the batches your own credential seeded and every first-sign-in batch. Under synthetic_seed_purge, it is only the batches your own credential seeded. Outside it are a batch a session seeded, a batch another credential seeded, and an account seeded before batches recorded the credential that seeded them. The purge refuses with this name under either grant, and the three reads under synthetic_estate. The refusal lists the accounts, and the purge's refusal also gives the grant that limits you. The purge under synthetic_seed_purge, and the three reads under synthetic_estate, check your reach before they check whether the account is synthetic. So every id outside your reach is refused with this name, a customer's account and an id that belongs to no account among them. Under synthetic_seed_purge, it also refuses a purge whose request_id another credential's purge already uses, and then it lists no account.",
"remedy": "Pass accounts your own credential seeded, or repeat from a credential holding super_admin, which reaches every synthetic account. Where the refusal lists no account, repeat the purge under another request_id.",
"members": {
"accounts": {
"type": "array",
"items": {
"type": "string"
},
"description": "The account ids the request gave that lie outside your reach, as you wrote them. The list is never empty. The member is left out where the request repeated a request_id another credential's purge carries."
},
"grant": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]*$",
"description": "The synthetic grant that bounds your credential, present on the purge's refusal."
}
}
},
{
"name": "account_paused",
"surfaces": [
"router",
"storage",
"egress",
"management_action",
"email"
],
"status": null,
"owner": "ACB-L0-26",
"summary": "The application's owning account has used up this month's free usage. Unlimited applications are exempt. The router returns 429 on every request to either hostname, including shell files and realm paths; scheduled runs are refused by the same name. Storage reads, lists, puts, deletes and grant mints, and egress calls before an upstream is reached, answer 429. Management acts that deploy, promote, roll back, restart or resume answer 409 before a row is written. A generate_image call past the month's free images is refused 409 before the provider is called, counting and charging nothing. New WebSocket upgrades are refused; open sockets close with code 1008 and reason `account paused`. On the router, `Retry-After` gives seconds until the pause ends at the first instant of the next UTC month. The router gives a request preferring HTML the pause page instead of JSON.\n\nOn the email surface, sending is refused 429 with `Retry-After` in seconds and `resets_at`, the instant the pause ends. Nothing is queued or counted.",
"remedy": "Wait until the instant the detail gives. Nothing you send ends the pause sooner."
},
{
"name": "account_picture_limited",
"surfaces": [
"management_action"
],
"status": 429,
"owner": "WEB-L0-28",
"summary": "tzMesh stopped the picture action at one of its limits: a generation already pending, the account's attempts or the service's runs for the UTC day, or the account's image store being full. The refusal does not tell which limit was reached.",
"remedy": "Try again later. Generation limits reset at UTC midnight; a pending run can be checked with the same request_id and prompt. A picture made in Settings before this deletion rule was in place stays until account erasure. Later Settings pictures are deleted once more than two days old, when the service next checks for old pictures, unless a participant holds them as pictures or a message carries them. Other stored images remain until account erasure. Waiting may not free a full image store."
},
{
"name": "account_picture_not_yet_served",
"surfaces": [
"realm_surface",
"dashboard_picture",
"management_action"
],
"status": 403,
"owner": null,
"summary": "The estate's `account_picture` setting reads `off`. The accounts service mints no token and spends no ticket. The dashboard picture route and the three page-only picture actions stop before any ticket, token request or tzMesh call.",
"remedy": "Nothing you do enables account pictures. The platform operator enables the setting when the estate serves them."
},
{
"name": "account_picture_unavailable",
"surfaces": [
"dashboard_picture",
"management_action"
],
"status": 503,
"owner": null,
"summary": "The signed-in account's picture read or picture action could not finish. A token request, relay call or image-byte request stopped short; `detail` identifies the step or stage with a short reason. A stopped act may already have registered a person or stored an image, or left its outcome unconfirmed.",
"remedy": "Try again later. If it keeps failing, report the short detail to support. This refusal includes no token or tzMesh address."
},
{
"name": "account_suspended",
"surfaces": [
"management_action",
"router",
"egress_tunnel",
"builder_sign_in",
"mcp_server",
"storage",
"egress",
"realm_surface",
"documentation",
"logging",
"push",
"email",
"deploy_progress",
"support_read",
"account_mail",
"dashboard_picture"
],
"status": null,
"owner": "API-L0-12",
"summary": "The account is suspended. On the management surface it is the account you act as (403). On the router it is the account the served hostname belongs to (503). At the tunnel seat it is the calling application's account (403). On the builder sign-in surface, a suspended account's sign-in completion is refused with this name (403), whether it comes from a provider or a passkey (ACS-L0-11). That refusal creates no session, sets no cookie, and issues no code. A grant is refused with this name (403) while the account recorded as its owner is suspended. This covers a transfer grant on the storage surface, an upload grant on the deploy command's progress read, and a secret grant on its one write. The grant works again once the account is reinstated, if it has not expired. On the egress surface, an egress key is refused with this name (403) while its owning account is suspended. The platform operator restores the account. On the support read surface, a consent and a read for a suspended account are refused with this name (403). The tzMesh site token route also refuses a suspended account with this name (403), and mints no token (ACS-L0-18).\n\nOn the dashboard picture surface, a current dashboard session for a suspended account is refused (403).",
"remedy": "Nothing you do corrects this. Only the platform operator restores the account, and the request succeeds again once the account is reinstated."
},
{
"name": "action_address_moved",
"surfaces": [
"management_action"
],
"status": 410,
"owner": "MAPI-10",
"summary": "You called an action with a bearer credential at the address a signed-in browser uses. Bearer calls moved to each action's own address, which the refusal gives, so nothing ran. A bearer revoke_token still works here.",
"remedy": "Repeat the same call, with the same name and body, at the address the refusal's address member gives.",
"members": {
"address": {
"type": "string",
"description": "The action's own address for a bearer call."
}
}
},
{
"name": "address_held_by_another_account",
"surfaces": [
"builder_sign_in",
"realm_surface"
],
"status": 409,
"owner": "ACB-L0-03",
"summary": "You tried to link a sign-in to an account, and the address its provider verified already belongs to a different account of the same realm. One verified address belongs to one account (ACC-L0-04). Nothing is linked and nothing is merged. You meet this refusal on the page that completes a link_identity link, and at the link the platform offers when a sign-in's address matches an existing account. On an application's end-user realm, an emailed-code sign-in that joins an existing account can meet it too. It applies on the builder realm and on an end-user realm alike.",
"remedy": "Sign in to the account that already has that address, through one of its existing sign-in methods or a code sent to that mailbox. Then complete the link from that account."
},
{
"name": "address_not_synthetic",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "MAPI-16",
"summary": "A staff read of a synthetic sign-in code gave an address outside the reserved fixture domain synthetic.turnzero.ai. The read returns codes only for an address at that domain. These are a first sign-in's codes, kept under the address until its confirmation creates the account, and after that the synthetic account's own. So nothing is returned, and the refusal does not repeat the address.",
"remedy": "Pass an address at the fixture domain in `address`, or the synthetic account's id in `account`, then repeat."
},
{
"name": "allowance_application_required",
"surfaces": [
"egress"
],
"status": 403,
"owner": "EGW-L0-08",
"summary": "The platform upstream ai-allowance accepts only an application's platform credential or a minted token bounded to one application. The allowance belongs to the application, and interactive work never draws on it (PRC-L0-06). An account-wide session or token is refused with this name.",
"remedy": "Make the call under the application's own platform credential, or under a token that mint_token bounds to that one application. For a local run, use the development environment's platform credential instead of your own sign-in."
},
{
"name": "allowance_busy",
"surfaces": [
"egress"
],
"status": 429,
"owner": "EGW-L0-06",
"summary": "Your application already has as many allowance calls in flight on this gateway replica as the platform allows at once, the AI_ALLOWANCE_MAX_CONCURRENT setting. The call is refused, and your application can retry after one of them ends.",
"remedy": "Wait for one of the application's allowance calls already in flight to finish, then repeat the request."
},
{
"name": "allowance_default_unavailable",
"surfaces": [
"egress"
],
"status": 503,
"owner": "EGW-L0-01",
"summary": "The allowance request uses default, but this gateway has no default model set or read. Nothing reached the provider.",
"remedy": "Name a model beginning gemini- in the path, or ask the operator to set ai_default_model, then wait about sixty seconds and retry. A failed settings read keeps the last successful reading."
},
{
"name": "allowance_exhausted",
"surfaces": [
"egress"
],
"status": 429,
"owner": "EGW-L0-06",
"summary": "The company's application on the unlimited plan has drawn its month's AI allowance. No customer application with a size meets this refusal. To continue, use the application's own stored key on its own declared upstream (PRC-L0-06). The body gives used, quota, and resets_at, the first instant of the next UTC month.",
"remedy": "Store your own key with store_secret, declare the upstream with declare_outbound_api, and call through it. Otherwise wait for the instant resets_at gives, the first instant of the next UTC month, then repeat the request."
},
{
"name": "allowance_feature_refused",
"surfaces": [
"egress"
],
"status": 400,
"owner": "EGW-L0-01",
"summary": "The allowance call's body is not a JSON object, or it asks for a feature the included allowance does not cover: tools, cached content, or an audio or video output modality (PRC-L0-06). The call is refused before any key is read.",
"remedy": "Send a JSON body that asks for text or image generation alone: no tools, no cached content, and no audio or video output modality. For one of those features, declare an upstream on your own stored key and call it there."
},
{
"name": "allowance_path_refused",
"surfaces": [
"egress"
],
"status": 403,
"owner": "EGW-L0-01",
"summary": "The platform upstream ai-allowance accepts one request shape: a POST to the generateContent or streamGenerateContent method of a model whose name opens with gemini-. Any other path, method, or model name is refused with this name, so the platform key pays for Gemini models and nothing else (PRC-L0-06). Whether the platform's key reaches a given Gemini model is the provider's own response, passed through.",
"remedy": "Send a POST to /v1beta/models/<model>:generateContent or :streamGenerateContent for a Gemini model. For another model family, method, or path, declare an upstream on your own stored key and call it there."
},
{
"name": "allowance_unavailable",
"surfaces": [
"egress"
],
"status": 503,
"owner": "EGW-L0-01",
"summary": "The platform has no key for the included AI allowance, or its price table has no row in effect, so no allowance call goes through. The detail says which. The key is missing where the gateway setting gives no vault secret, or the core vault has no version under that name (the credential register's ai_allowance_key row). The price table is empty until the operator adds a row.",
"remedy": "Nothing you do corrects this, because only the platform's operator stores the allowance key or adds the price row. Until then, call a declared upstream on your own stored key."
},
{
"name": "app_credential_not_admitted",
"surfaces": [
"management_action",
"mcp_server"
],
"status": null,
"owner": "SEC-L0-07",
"summary": "You presented the application's platform credential where it is not accepted. On the management plane only read_account accepts it, and every other action refuses it (403). At the MCP server it connects nothing (401 challenge).",
"remedy": "Sign in through your connected tool, or present a token minted by mint_token, and repeat the call. Present the application's platform credential only on the storage and egress routes, on the end-user verification route, and on read_account."
},
{
"name": "application_credential_required",
"surfaces": [
"logging"
],
"status": 403,
"owner": "LGS-01",
"summary": "The logging ingest accepts only the application's platform credential or a minted token bounded to that application. An account credential does not identify a log stream.",
"remedy": "Send the batch under the application's platform credential, or under a token bounded to that one application. Mint such a token with mint_token where you have none."
},
{
"name": "application_other_account",
"surfaces": [
"management_action",
"storage"
],
"status": 403,
"owner": "MAPI-14",
"summary": "The application id in your request belongs to a live application of another account, not the account you are signed in as. Every management action that looks up an application by its id refuses with this name instead of no_such_application, and so does the storage surface's area declaration. The detail gives the account you act as and, from the turnzero command or an AI tool's connection, the likely cause, or, from the signed-in site, to sign in to the account that holds the application, and nothing about the other account.",
"remedy": "Compare turnzero whoami with read_account over your AI tool's connection: the command and the connection are likely signed in to different accounts. Make the call from the one signed in to the account that has the application, or use an id list_applications returns. From the signed-in site, sign in as the account that holds the application."
},
{
"name": "application_required",
"surfaces": [
"management_action",
"storage"
],
"status": 400,
"owner": "OST-L0-01",
"summary": "You declared a storage area or an upstream under an account-wide credential and gave no application.",
"remedy": "Pass the application the area or upstream binds to: the identifier list_applications returns. Every area and every upstream binds to one application. On the storage wire, a mint under the application’s platform credential or under a token bounded to one application may leave the member out, and it then defaults to that application."
},
{
"name": "approval_expired",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "API-L0-07",
"summary": "The pending action expired before you approved it.",
"remedy": "Request the action again where it is still wanted. The new request creates a new pending action with its own approval link to approve in the browser."
},
{
"name": "approval_not_found",
"surfaces": [
"management_action"
],
"status": 404,
"owner": "API-L0-07",
"summary": "No pending action has that id, so there is nothing to approve or decline.",
"remedy": "Open the approval link exactly as your session printed it. Where read_approval_status from the requesting tool also finds no record, request the action again."
},
{
"name": "approval_state_approved",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "API-L0-07",
"summary": "The pending action is already approved. Approve and decline work only on a pending action that is still in the requested state.",
"remedy": "No further click is needed. Read the outcome through read_approval_status from the requesting tool."
},
{
"name": "approval_state_completed",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "API-L0-07",
"summary": "The pending action already completed. Approve and decline work only on a pending action that is still in the requested state.",
"remedy": "Nothing remains to approve or decline. Read the recorded outcome through read_approval_status from the requesting tool."
},
{
"name": "approval_state_declined",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "API-L0-07",
"summary": "The pending action is already declined. Approve and decline work only on a pending action that is still in the requested state.",
"remedy": "Where the act is still wanted, request it again. The new request creates a new pending action with its own approval link to approve in the browser."
},
{
"name": "approval_state_executing",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "API-L0-07",
"summary": "The pending action is running. Approve and decline work only on a pending action that is still in the requested state.",
"remedy": "Wait for the execution to finish, then read the outcome through read_approval_status from the requesting tool. No further click is needed."
},
{
"name": "approval_state_expired",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "API-L0-07",
"summary": "The pending action has already expired. Approve and decline work only on a pending action that is still in the requested state.",
"remedy": "Request the action again where it is still wanted. The new request creates a new pending action with its own approval link to approve in the browser."
},
{
"name": "approval_state_failed",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "API-L0-07",
"summary": "The pending action already failed. Approve and decline work only on a pending action that is still in the requested state.",
"remedy": "Read the outcome through read_approval_status and check the subject's current state. Where the act is still wanted, request it again and approve the new pending action in the browser."
},
{
"name": "approval_state_gone",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "API-L0-07",
"summary": "The pending action's record disappeared while your approval or decline was being written.",
"remedy": "Read the record through read_approval_status from the requesting tool. Where it no longer exists, request the action again and approve the new pending action in the browser."
},
{
"name": "approval_wrong_account",
"surfaces": [
"management_action"
],
"status": 403,
"owner": "API-L0-07",
"summary": "The browser you approved from is signed in to a different account from the one that made the request.",
"remedy": "Sign in to the browser as the account that made the request, then open the approval link again."
},
{
"name": "area_name_reserved",
"surfaces": [
"management_action",
"storage"
],
"status": 400,
"owner": "OST-L0-01",
"summary": "You declared a new storage area under a name beginning `export-` or `deploy-`, or of the exact form `images-<application id>`. These belong to the platform: request_export creates export areas under the first, deploy's upload form creates deploy areas under the second, and generate_image creates image areas under the third. Any other name beginning `images-` stays yours. The refusal applies on the minting route, through declare_storage_area, and through submit_manifest. An area that already exists under any of them can be declared again, as any area can.",
"remedy": "Declare the area under a name that begins with neither `export-` nor `deploy-` and is not `images-` followed by an application id. An application's export area belongs to the platform: request_export creates it, and the line request_export with download: true returns downloads its files. An application's deploy area belongs to the platform too: deploy's upload form creates it and writes to it. An application's image area belongs to the platform too: generate_image creates it and writes to it."
},
{
"name": "area_not_empty",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "OST-L0-01",
"summary": "You tried to undeclare a storage area that still contains a file in one of its environment partitions, so the declaration remains.",
"remedy": "Remove the files first through the storage routes, from both environments' partitions, then undeclare the area again. Or keep the area."
},
{
"name": "area_scope_refused",
"surfaces": [
"management_action",
"storage"
],
"status": 403,
"owner": "OST-L0-03",
"summary": "The credential or operation does not reach the area. An area accepts its own application's credentials and an account-wide credential that no bounding grant bounds. A credential bounded by any of the bounding grants MAPI-16 lists, `tztrack`, `tzmesh`, and `device_sign_in` among them, reaches no area of the account (MAPI-16).\n\nOn mint_upload_grant, the area you gave is bound to an application other than the one the call gives. On list_storage_files and read_storage_file, the area you gave is bound to an application other than the one the call gives, or is the platform's deploy area.\n\nOn request_export with download: true, your credential does not reach the export area. On the platform's deploy area, `deploy-<application id>`, only the upload grant `deploy` returns reaches the file routes. Every other credential is refused there, the account's own included.\n\nOn the platform's export area, upload grants and file-route `PUT` calls are refused. OST-L0-01 identifies that area by its name and bound application.",
"remedy": "Where the credential lacks reach, repeat the request with a credential the area accepts: an account-wide credential that no bounding grant bounds, or the credential of the application the area is bound to. For a wider reach, mint a second token from a signed-in session through mint_token; you cannot widen the token you have. For a token bounded by the synthetic_seed_purge, synthetic_estate, publication, feedback_queue, or issues grant, mint a token without the grant, or call from the owner's session.\n\nFor mint_upload_grant, list_storage_files, and read_storage_file, pass the application the area is bound to, or an area bound to the given application. For the deploy area, deploy by a line. Call `deploy_command` with the application, naming no environment. Run the line it returns once, as given, from the application's folder, and make its `next` call. No credential of yours reads, lists, or deletes that area's files.\n\nFor the platform's export area, use the file routes to read, list or delete files. Only the export writes it; changing credentials admits no upload grant or file-route `PUT`.",
"members": {
"scope": {
"type": "object",
"description": "The reach of the credential presented: the whole account, or the one application a token is bounded to, with the bounding grant where one bounds it.",
"properties": {
"kind": {
"type": "string",
"description": "The kind of reach: account or application."
},
"application": {
"type": "string",
"description": "The id of the application the token is bounded to, present where kind is application."
},
"grant": {
"type": "string",
"description": "The bounding grant the credential carries, present where one bounds it."
}
}
}
}
},
{
"name": "artifact_area_mismatch",
"surfaces": [
"management_action"
],
"status": 403,
"owner": "PLD-L0-63",
"summary": "The area is one a deploy cannot read. On deploy, the artifact's area; on deploy_files, a `stored` entry's area. A deploy reads a stored file only from an area bound to the application it deploys (OST-L0-03). Before reading any byte, it refuses an area the account has not declared, an area bound to another application of the account, and the platform's deploy area, `deploy-<application id>`. On deploy_files the refusal falls in the list's order, with `kept` and `refused`.",
"remedy": "Upload the file into an area declared with the application you deploy, through declare_storage_area with that application or the application's own credential on the minting route. Then call deploy, or deploy_files with a `stored` entry that uses that area. An area binds to one application when it is declared and never moves to another, so a file for another application goes into an area of its own. A zip in the deploy area is deployed by the upload form: call `deploy` with the `upload` its preparing call returned.",
"members": {
"kept": {
"type": "array",
"description": "On a `deploy_files` list whose entries are refused one by one, each entry kept and each entry by `sha256` alone whose file the platform holds and could read as the refusal was built, in the list's order. A retry gives each by its `sha256`.",
"items": {
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "The entry's path, as the list gave it."
},
"sha256": {
"type": "string",
"description": "The SHA-256 the platform computed over the bytes it kept, the hash a retry gives."
}
}
}
},
"refused": {
"type": "array",
"description": "On a `deploy_files` list whose entries are refused one by one, each refused entry, in the list's order. The list is never empty, and its first entry is the one the detail cites.",
"items": {
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "The entry's path, as the list gave it."
},
"error": {
"type": "string",
"description": "The refusal name the entry met."
},
"received_sha256": {
"type": "string",
"description": "With `deploy_files_hash_mismatch`: the SHA-256 the platform computed over the bytes it received or read, which the hash the call gave did not match."
}
}
}
}
}
},
{
"name": "artifact_hash_mismatch",
"surfaces": [
"management_action"
],
"status": 400,
"owner": "PLD-L0-63",
"summary": "On deploy: the artifact bytes in your account's area hash to a different value from the one your request gives.",
"remedy": "Recompute the stored file's hash, or upload the intended bytes again, then call deploy with the stored file's hash."
},
{
"name": "artifact_layout_invalid",
"surfaces": [
"management_action"
],
"status": 400,
"owner": "PLD-L0-63",
"summary": "On deploy: the zip's layout cannot run. It has no root package.json that parses as a JSON object, or it has neither a scripts.start nor a root server.js for npm start to run. A root package.json or manifest.json that declares more than 1 MiB is refused too. So is a zip past 65,535 entries, past 128 MiB declared by its files and folders, or past 500,000 name segments. So is an entry name the image build refuses: one longer than 4,096 bytes or 128 segments, or one with a backslash or a NUL, a drive, or an absolute or climbing path. So is one path listed as both a file and a folder. So is a workspaces pattern the platform does not read, a root manifest.json nested past 64 levels, and a root or workspace member binding.gyp with no .node file in its folder. So is a `client/` folder whose files pass 2,000 files, 25 MiB in one file, or 50 MiB in all (SVC-L0-26). The detail gives the cause. No version row is inserted and no deploy is counted.",
"remedy": "Zip the folder's contents with package.json at the top, give it a start script for the server entry, upload, and call deploy again. Create a serverless application for static sites; read_documentation's page /cloud/guides/publish-a-static-site/ shows how. On Windows, build the zip with the tar.exe command that step 3 of read_documentation's page /cloud/getting-started/deploy-an-application/ gives, which the detail points to, because Compress-Archive writes a backslash between segments. Ship the root's or a workspace member's native module prebuilt, with its .node file where step 3 of read_documentation's page /cloud/getting-started/deploy-an-application/ says. Keep large media out of `client/` and in a storage area."
},
{
"name": "artifact_not_found",
"surfaces": [
"management_action"
],
"status": 404,
"owner": "PLD-L0-63",
"summary": "No file has the given area and name in your account's partition. For `deploy`, this is the artifact. For `deploy_files`, it is a `stored` entry in the deploy target's partition; the detail gives the application's upload page. For a `deploy_files` list, the refusal follows list order and includes `kept` and `refused`.",
"remedy": "Upload the file into an area bound to the application you deploy, then call deploy with that area and file name. Where the file is in the other environment's partition, pass that environment in `artifact.environment`. For a deploy_files `stored` entry, ask the person to upload the file on the application's page given in the detail, then send the list again with the file name shown on the page.",
"members": {
"kept": {
"type": "array",
"description": "On a `deploy_files` list whose entries are refused one by one, each entry kept and each entry by `sha256` alone whose file the platform holds and could read as the refusal was built, in the list's order. A retry gives each by its `sha256`.",
"items": {
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "The entry's path, as the list gave it."
},
"sha256": {
"type": "string",
"description": "The SHA-256 the platform computed over the bytes it kept, the hash a retry gives."
}
}
}
},
"refused": {
"type": "array",
"description": "On a `deploy_files` list whose entries are refused one by one, each refused entry, in the list's order. The list is never empty, and its first entry is the one the detail cites.",
"items": {
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "The entry's path, as the list gave it."
},
"error": {
"type": "string",
"description": "The refusal name the entry met."
},
"received_sha256": {
"type": "string",
"description": "With `deploy_files_hash_mismatch`: the SHA-256 the platform computed over the bytes it received or read, which the hash the call gave did not match."
}
}
}
}
}
},
{
"name": "artifact_unreadable",
"surfaces": [
"management_action"
],
"status": 400,
"owner": "PLD-L0-63",
"summary": "On deploy: the artifact's bytes do not read as a zip archive, or an entry the deploy reads inflates past the size it declares, and the detail gives the entry. The deploy reads the zip right after its bytes and hash, before the in-flight check and the application's deploys-per-day quantity. So no version row is inserted and no deploy is counted.",
"remedy": "Zip the project folder's contents, with package.json at the zip's root, upload the zip, and call deploy again."
},
{
"name": "audience_mismatch",
"surfaces": [
"realm_surface"
],
"status": 403,
"owner": "ACS-L0-09",
"summary": "The work-account or Sign in with Apple id_token has an audience other than the declared client.",
"remedy": "On the work-account route, set entra.client_id with configure_app_sign_in to the client id of the tenant app registration the sign-in uses. On the Sign in with Apple route, set apple.services_id to the Services ID the sign-in uses. Then ask the end user to sign in again."
},
{
"name": "authentication_required",
"surfaces": [
"management_action",
"mcp_server",
"storage",
"egress",
"realm_surface",
"router",
"logging",
"push",
"email",
"deploy_progress",
"support_read",
"account_mail"
],
"status": 401,
"owner": null,
"summary": "No credential resolved to an account. The refusal is the usual challenge giving the protected-resource metadata, at the internal resolve endpoint gate, or at the audience gate the router applies (ADM-L0-05). On the management and MCP surfaces, the detail says whether the connection presented no credential or presented one that resolved to no account (MCP-02). Where the credential you presented has the form of a short-lived grant and the platform has no grant of that value, the detail says the grant was not accepted (MAPI-03). On the support read surface, a consent or its end without a signed-in support cookie, and a read without a live support read token, are refused with this name (401).\n\nA page-only action is refused with this name, without a `WWW-Authenticate` challenge, where no API cookie call is admitted (MAPI-03). No bearer can call that row.",
"remedy": "Where no credential was presented, nothing was done. Ask the person to sign in to Turn Zero: in Claude Code they type /mcp and choose the server, in Codex they finish the page the add line opened or run codex mcp login, and the Claude app offers it at the connector. Then make the call again.\n\nThe turnzero command has its own sign-in, which a tool's sign-in does not make. A signed-in tool chooses its deploy route with read_documentation, page /cloud/getting-started/ways-to-deploy/. It authorizes the computer where the command is selected; where the command is unavailable, the tool uses deploy_files within its caps and the upload route past them. The person runs turnzero login only where no in-tool route works, or to renew their own login. A job presents a minted token or the credential the surface takes.\n\nWhere the credential you presented resolved to no account, sign in again and make the call again. On an application's routes, have the end user sign in again.\n\nWhere a grant was not accepted, it expired and was removed, or its value was changed. If the command or line a tool call returned had the grant, make that call again and run the fresh command it returns. If your application requested the grant, request another. On an application's routes, the serving router refused the request before it reached the application. Test the application's own authentication branches in its offline tests or in a local run.\n\nFor a page-only act, sign in on this site and use its page. A bearer credential does not admit the call."
},
{
"name": "authorization_pending",
"surfaces": [
"builder_sign_in",
"management_action"
],
"status": 400,
"owner": null,
"summary": "No one has approved the sign-in yet, so no token is issued. Your program polled the token endpoint under the device-code grant before you allowed the request on the verification page (RFC 8628), or the turnzero command polled mint_token for its device sign-in before you approved it on the computer login page.",
"remedy": "Keep polling: the answer changes once the sign-in is approved. At the token endpoint, open the verification link your program printed, sign in, allow the request, and poll at the interval the device authorization response gave. For mint_token, the turnzero command polls every five seconds until its request's expires_at, and the person approves on the page its link opens."
},
{
"name": "balance_short",
"surfaces": [
"management_action"
],
"status": 402,
"owner": "ACB-L0-26",
"summary": "The usage balance left is not more than the monthly option's charge for the days left in this month. The option stays off and nothing was charged.",
"remedy": "Try again when the balance is more than the charge for the days left in this month."
},
{
"name": "batch_too_large",
"surfaces": [
"logging"
],
"status": 413,
"owner": "LGS-L0-13",
"summary": "The batch body is larger than 512 KiB, or it contains more than 500 records, entries and counters together.",
"remedy": "Split the batch into parts of at most 500 records and 512 KiB of body each, then send the parts in order."
},
{
"name": "binding_refused",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "EGW-L0-01",
"summary": "You called declare_outbound_api for an upstream bound to another application of the account. A bound upstream is never unbound, and never bound again to another application. On submit_manifest, another application of the account declared an entry's name after the submission's check, so that entry was not written. The manifest stays recorded, and the detail lists the upstreams declared and those not.",
"remedy": "Keep the existing binding, or declare the upstream for the other application under a different name with declare_outbound_api. Ending the upstream with declare_outbound_api and remove true ends the binding. On submit_manifest, rename the entry and submit the manifest again before the next deploy or promote; that submission declares the remaining upstreams.",
"members": {
"application": {
"type": "string",
"description": "The id of the application the existing upstream of that name is bound to, which is not the application this declaration gave."
}
}
},
{
"name": "blueprint_required",
"surfaces": [
"management_action",
"egress"
],
"status": 403,
"owner": "ACB-L0-89",
"summary": "The account does not hold the tzTrack product profile, `tztrack`, which opens its issue spaces; every account holds it by the product rule. On create_space, share_space, list_space_members, rename_space, and relay_issue_act it refuses every call after the dispatcher's text check and ahead of the request's form, the space's owner, and the token's level, nothing created or relayed. A connected tool lists none of the five to the account. On mint_token it refuses a token asking for the issues grant. It refuses a token asking for the tztrack grant the same way, at the mint and at the code's exchange. On the egress gateway it refuses a hosted application's call through its binding to a space of its account.",
"remedy": "Every account holds tzTrack by the product rule, so no act adds it. Repeat the request; read_account lists the products the account holds."
},
{
"name": "bot_check_failed",
"surfaces": [
"support_read"
],
"status": 403,
"owner": "MAPI-29",
"summary": "A signed-out visitor's message to the support chat carried no bot-check token, or one the check did not pass, on an estate that sets a bot check. The message was not sent to the support agent.",
"remedy": "Reload the Questions page and send the message again, so the page gets a fresh token, or sign in, since a signed-in chat needs no check."
},
{
"name": "bound_setting_unreadable",
"surfaces": [
"management_action"
],
"status": 502,
"owner": "MAN-14",
"summary": "On deploy, promote, roll_back, or a platform restart: a setting the manifest binds refers to a secret whose entry exists at the environment's scope, but the store did not return its value. The row ended failed before the compute apply, so the serving compute is untouched. The detail gives the setting and the secret.",
"remedy": "Deploy, promote, or roll back again. The platform retries a restart at its next pass. If the refusal repeats, report it with its detail. Storing the value again with store_secret does not help while the store does not respond."
},
{
"name": "browser_session_required",
"surfaces": [
"management_action"
],
"status": 403,
"owner": null,
"summary": "The approval action was called somewhere other than its approval page, or a page-only action received an `Authorization` header, even beside a cookie. Approval reads no credential on the actions routes (MAPI-05); a page-only action admits only the API cookie call and reads no bearer (MAPI-03).",
"remedy": "For approval, open the approval link in a signed-in browser and approve or decline there, then read_approval_status. For a page-only act, use its signed-in page; no bearer credential can call it."
},
{
"name": "build_wait_exceeded",
"surfaces": [
"management_action"
],
"status": 503,
"owner": "PLD-L0-63",
"summary": "On deploy: the image or function build waited fifteen minutes for its turn behind other builds on the same control plane process, and never started. Nothing was built or applied, and the serving version is untouched. The history row ends failed with this outcome at the image_build step.",
"remedy": "Deploy again; the new deploy takes its own turn. If the wait repeats, the platform is busy with other builds, so wait a few minutes before deploying again."
},
{
"name": "cell_move_in_flight",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "API-L0-31",
"summary": "An unfinished cross-cell move of the application refuses a database move. No pending action or database move is created. Production keeps its current database size.",
"remedy": "Repeat the request once the application's move to the other cell ends."
},
{
"name": "cell_not_configured",
"surfaces": [
"management_action"
],
"status": 503,
"owner": "PLD-L0-130",
"summary": "No hosting cell is open to the act. The actions create_application, submit_manifest, deploy, deploy_files, and declare_storage_area refuse with it when the placement registry has cells but no admitting cell. The action create_application also refuses with it when there is no admitting routing tier. The actions deploy and deploy_files refuse with it when no cell is registered and no deploy configuration exists, or when the application's placement points to no registered cell. A deploy, a promote, or a redeploy under the placement rule also refuses with it when the group the environment would be placed in is on a cell that records no cluster. The action submit_manifest refuses with it when the application has no placement to provision a database on. A promote or a production deploy refuses with it at its database_pair step, the history row ending failed, when the production environment has no placement to provision a database on. The action read_logs refuses with it when the cell's log workspace is not configured. It also refuses with it, for an environment that runs as a pod, when the cell records no cluster or the group is not registered. The action delete_environment refuses with it after its approval when the development environment has no placement row and no admitting cell or routing tier exists, or no cell is registered (PLD-L0-130).",
"remedy": "Nothing you do corrects this. Report the refusal with its detail, and repeat the request once the platform's operator has registered an admitting cell and routing tier, or has finished configuring the cell."
},
{
"name": "cell_timeout",
"surfaces": [
"management_action"
],
"status": 503,
"owner": "PLD-L0-80",
"summary": "The platform's hosting cell did not respond in time, so the call could not finish. Nothing in the request was wrong. An action whose call waits on the hosting cell can refuse with it, read_status and a pod environment's console read among them; an approved destructive action's execution records execution_failed instead. The platform records the failure under the reference the detail gives.",
"remedy": "Repeat the call after a short wait. Where the call changes something, call read_status first, because the change may already be made. If the refusal repeats, report it and quote the reference its detail gives."
},
{
"name": "cell_unavailable",
"surfaces": [
"management_action"
],
"status": 503,
"owner": "PLD-L0-130",
"summary": "No admitting hosting cell has headroom under its nominal capacity, so the application cannot be placed. The actions create_application, submit_manifest, deploy, deploy_files, and declare_storage_area refuse with it. The act set_app_size, when moving production to shared-1gb, and the operator's placement on the unlimited plan refuse where the cell's container-grain placements reach their bound. The act delete_environment refuses with it after its approval when the development environment has no placement row (PLD-L0-130).",
"remedy": "Nothing you do corrects this. Report the refusal with its detail, and repeat the request once the platform's operator has registered a cell with headroom or raised a cell's nominal capacity."
},
{
"name": "chat_not_yours",
"surfaces": [
"support_read"
],
"status": 403,
"owner": "MAPI-29",
"summary": "The chat in the consent, or in its end, was not started by the signed-in account: it was started while signed out, or by another account, or the id is not a chat id this site made. Nothing is shared or ended. On the chat's message and turn posts, the chat id's signature holds neither for the signed-in account nor for no account: a chat started while signed in whose sign-in has since ended, or a forged id. Nothing is sent.",
"remedy": "Start a new chat while signed in, and share from that chat. On the message post, start a new chat, signed in again or as a visitor, and send the message there."
},
{
"name": "client_secret_unreadable",
"surfaces": [
"realm_surface"
],
"status": 403,
"owner": "ACS-L0-09",
"summary": "The work-account client secret could not be read from the platform's secret store at the token exchange. Or, on the Apple route, the signing key could not be read or could not sign the client secret.",
"remedy": "Store the client secret or the Apple signing key again with store_secret, giving this application and the realm's environment, under the configured entra.client_secret_name or apple.key_secret_name. Store the Apple key as an ES256 key in PKCS#8 text. Then ask the end user to sign in again. If the refusal repeats, report it to the platform's operator, because nothing further on your side corrects it."
},
{
"name": "client_upgrade_required",
"surfaces": [
"router"
],
"status": 426,
"owner": "SVC-L0-11",
"summary": "The serving router refuses with this on an application request whose `x-turnzero-cloud-client` header gives a native client declared on the realm, at a version below that client's minimum version. The body includes `minimum_version`, the oldest version accepted, and `update_url`, the store link declared for the client, null where none is declared. The request reaches no application code and counts toward no request limit.",
"remedy": "An end user installs the app's current version from the update URL and opens it again. Where the refusal was not intended, lower or remove the client's minimum_version with configure_app_sign_in on the environment's realm."
},
{
"name": "cloud_required",
"surfaces": [
"management_action"
],
"status": 403,
"owner": "ACB-L0-76",
"summary": "You called one of tzCloud's actions from an account that does not have tzCloud. Every account holds tzCloud by the product rule, and an operator account has every product. A connected tool lists no such action for that account, and a call to one is refused with this name, which gives the action's name.",
"remedy": "Every account holds tzCloud by the product rule, so no act adds it. Repeat the request; the read_account action lists the products the account has."
},
{
"name": "command_too_old",
"surfaces": [
"management_action",
"deploy_progress"
],
"status": 426,
"owner": "PLD-L0-109",
"summary": "Your command is older than this plane serves. The request's `User-Agent` opens with `turnzero-cloud/<version>` or `turnzero/<version>`, at a version below the floor this plane sets: the oldest command whose flows it still serves correctly. The body gives the floor as `minimum_version`, beside `contract_version`. The plane never refuses `revoke_token` this way, so an old command's `logout` still ends its token. The command route of `sign_in_test_end_user` uses the plane's floor, 0.37.0, and returns that `minimum_version` for a lower version (PLD-L0-109).",
"remedy": "Update an installed command with its install line, `npm install -g turnzero@<tag>`: the tag is `latest` on production and `next` on development. Then run the line again. Where the line runs through npx, take a fresh line from your tool's deploy_command call, or run this line again once its tag points to the floor's version or a later one. A line with one version's own tarball address runs only that version, so take a line with a newer one.",
"members": {
"minimum_version": {
"type": "string",
"description": "The floor: the oldest command version, `turnzero-cloud` or `turnzero`, whose flows this plane still serves correctly, as `<major>.<minor>.<patch>`."
}
}
},
{
"name": "context_changed",
"status": 409,
"surfaces": [
"management_action",
"mcp_server"
],
"owner": "CTX-07",
"summary": "The continuation stamp you sent no longer matches the catalog or the content you can see.",
"remedy": "Repeat the request from offset zero without a stamp, then continue paging with the stamp the new response gives."
},
{
"name": "context_not_found",
"status": 404,
"surfaces": [
"management_action",
"mcp_server"
],
"owner": "CTX-07",
"summary": "The content id is not in the catalog you can currently see, or a page route is not in the tree's manifest.",
"remedy": "Call read_context with no id and copy the identifier exactly as the catalog lists it, then repeat read_context with it. For an identifier beginning docs:, call read_documentation instead, with the tree and part its catalog row gives. For a page, pass its route as the tree's index prints it, which the manifest lists."
},
{
"name": "context_unavailable",
"status": 503,
"surfaces": [
"management_action",
"mcp_server"
],
"owner": "CTX-07",
"summary": "An indexed source or a built documentation tree is unavailable, or the platform could not read a product's practices or skills from that product's own server.",
"remedy": "For a product's practices or skills, read again in a short while: the platform reads them from the product's server again. For an indexed source or a documentation tree, nothing you do corrects this: the platform restores it by its next publish or release, so retry later and report the refusal with its detail if it persists."
},
{
"name": "continue_new_removed",
"surfaces": [
"builder_sign_in",
"realm_surface"
],
"status": 410,
"owner": "ACC-L0-04",
"summary": "The continue-new route is retired. The platform no longer creates a separate account under an address that an existing account already has. The only way on is to link the sign-in to that account.",
"remedy": "Link the two accounts instead. Sign in with a method the existing account already has, or, where the page offers it, request a code to that address and type it. If the linking page has closed, start the sign-in again."
},
{
"name": "creation_contradicts_audience",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "ADM-L0-05",
"summary": "On configure_app_sign_in: the manifest declares the invited audience, and the call sets creation to open. Under an invited audience, both realms create accounts by invitation only, from the declaration on.",
"remedy": "Leave creation out of the call, or set it to invited. To allow a first sign-in without an invitation, change the manifest's audience to public with submit_manifest first.",
"members": {
"audience": {
"type": "string",
"description": "The audience the application's manifest declares, invited at this refusal."
},
"creation": {
"type": "string",
"description": "The creation mode the call gave, open at this refusal."
}
}
},
{
"name": "credential_lookup_busy",
"surfaces": [
"storage",
"egress",
"logging",
"push",
"email"
],
"status": 503,
"owner": "PLD-L0-67",
"summary": "On the storage, egress, logging, push, and email wires, the gateway replica could not start looking up the presented credential. Its wait bound passed, two seconds by default, or its places for waiting lookups were full. Each replica limits the lookups its credential cache cannot serve. The request was not processed and counts toward no rate window.",
"remedy": "Repeat the same request unchanged after one second, the time the Retry-After header gives. It was not processed, so a repeat causes no duplicate effect. A credential the gateway looked up within its cache interval, 30 seconds by default, is not looked up again."
},
{
"name": "credential_not_in_custody",
"surfaces": [
"management_action",
"egress"
],
"status": 409,
"owner": "SCRT-L0-08",
"summary": "The declared credential name is not in the account's custody at the scope reached; store_secret puts it there. A name stored only for the application's other environment is refused too, since each environment reads its own scope and the account scope. On declare_outbound_api, where the entry ended while the declaration was being written and the write cannot be taken back, the declaration remains as written and the detail says so.",
"remedy": "Store a value under the declared credential name with store_secret, for the account or for the application's environment, then repeat the request. Where the detail gives the other environment, store this environment's own value under the same name at this environment's scope of the application. Each environment reads its own scope, so development can have a test key and production a live one. A key both environments share can instead be stored once at the account scope under a new name. Every upstream of the account that declares that name reads it, so declare the upstream again with that name. Include the upstream's `sdk_settings` in that call, or omit the member, which keeps them; `sdk_settings` null removes them and ends the upstream's egress keys. Where the detail says the declaration remains, declare the upstream again with a stored credential name, or store the credential again."
},
{
"name": "credential_unreadable",
"surfaces": [
"egress"
],
"status": 502,
"owner": "EGW-L0-03",
"summary": "The upstream's stored secret exists, but the egress gateway could not read its value.",
"remedy": "Retry the request. If the refusal repeats, store the secret again with store_secret, or report the refusal with its detail."
},
{
"name": "credit_flag_held",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "ACB-L0-103",
"summary": "An open payment dispute prevents clearing this account’s credit flag. The flag was not changed.",
"remedy": "Wait for the dispute to close, read the purchases and flag again, and give a reason if clearing is still needed.",
"members": {
"flag": {
"type": "object",
"description": "The account's credit flag and any recorded clearing.",
"properties": {
"purchase": {
"type": "string",
"description": "The purchase that raised the flag."
},
"cause": {
"description": "The return that raised it. Current values include `refund`, `dispute`.",
"type": "string"
},
"shortfall": {
"type": "string",
"description": "The shortfall as a dollars string."
},
"shortfall_micros": {
"type": "integer",
"description": "The shortfall in whole micro-dollars, zero or greater."
},
"flagged_at": {
"type": "string",
"description": "The instant the flag was raised."
},
"cleared_at": {
"type": [
"string",
"null"
],
"description": "The clearing instant, or null while not cleared."
},
"cleared_by": {
"type": [
"string",
"null"
],
"description": "The operator who cleared it, or null."
},
"cleared_reason": {
"type": [
"string",
"null"
],
"description": "The recorded clearing reason, or null."
}
}
}
}
},
{
"name": "credit_sales_off",
"surfaces": [
"management_action"
],
"status": 403,
"owner": "ACB-L0-101",
"summary": "Credit sales are off on this site. The call opens no checkout and charges nothing.",
"remedy": "Credit cannot be bought on this site while sales are off."
},
{
"name": "custody_entry_missing",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "ACS-L0-09",
"summary": "On configure_app_sign_in or configure_push: the work-account client secret, Apple signing key, or push provider credential the call gives is not in custody under the application scope at the call's environment. On submit_manifest, the entry of a route credential the realm member gives ended after the check, so that environment's realm was not configured. The manifest stays recorded, and the detail lists the realms done and those not. On create_environment, the same applies on development, and the member is not recorded there.",
"remedy": "Store the secret with store_secret, giving this application and the environment, under the name you will configure. Then call configure_app_sign_in again with that name in entra.client_secret_name or apple.key_secret_name, or configure_push again with it in apns.key_secret_name or fcm.service_account_secret_name. On submit_manifest, store the value again, or under a new name you then set in the realm member, and submit the manifest again. On create_environment, store the value again and call it again, or use a new name in the member and submit the manifest.",
"members": {
"client_secret_name": {
"type": "string",
"description": "The secret name the call, or the manifest's realm member, gave as the work-account client secret, the Apple signing key, or the push provider credential, for which custody holds no entry at the application's scope."
},
"application": {
"type": "string",
"description": "The id of the application whose realm the call, the submission, or create_environment configures, and at whose scope the entry was looked up."
}
}
},
{
"name": "custody_entry_unmovable",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "ACS-L0-09",
"summary": "On configure_app_sign_in: the cell's realm vault already has the client secret's or the key's name at another version, so the value cannot move there. Nothing moved and no row was written. On submit_manifest, the realm vault took the name after the check, so that environment's realm was not configured. The manifest stays recorded, and the detail lists the realms done and those not. On create_environment, the same applies on development, and the member is not recorded there.",
"remedy": "Store the value under a new name at the application's scope with store_secret, then call configure_app_sign_in again with that name in entra.client_secret_name or apple.key_secret_name. On submit_manifest or create_environment, store the value under a new name, change the realm member to it, and submit the manifest again."
},
{
"name": "custom_domain_capacity",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "SVC-L0-25",
"summary": "The manifest declares a custom domain, and the estate's rows that have or may have a provider resource are at the estate's bound, counted when the row is inserted or a failed row returns. Those rows are every row that is not failed, and every failed row whose resource name remains. The bound is 99 at the beta, and nothing is written.",
"remedy": "Nothing you do raises the bound. Ask the platform operator to raise the estate's bound, then call submit_manifest again. Removing the custom_domain row from the manifest lets the submission through without the domain.",
"members": {
"bound": {
"type": "integer",
"description": "The estate's bound on custom domains, the count of rows that hold or may hold a provider resource its apps edge admits at most."
}
}
},
{
"name": "custom_domain_invalid",
"surfaces": [
"management_action"
],
"status": 400,
"owner": "SVC-L0-25",
"summary": "The manifest's custom_domain row gives a hostname the platform refuses, and the refusal states the reason. The reasons are an apex, a reserved name (one under a serving suffix, the company domain, or the apps edge name), a public suffix, and held. Held means another row of the platform's table has the name, failed and detaching rows among them. It also means the application's own row has another domain or is in the detaching state; the detail then says to remove that row.",
"remedy": "Declare a different hostname, then call submit_manifest again: for an apex, a label under it such as www; for a held name, a name of your own. Where your own row has another domain, remove the row, submit again, and wait until read_status no longer shows custom_domain before declaring the new name. The manifest schema refuses a hostname of fewer than three labels, or a wildcard, before this check.",
"members": {
"domain": {
"type": "string",
"description": "The declared hostname."
},
"reason": {
"type": "string",
"description": "Why the hostname is refused: apex (no label before its registrable domain under the Public Suffix List), reserved (a platform name), public_suffix, or held. Held means another row of the platform's table holds the name, a detaching or failed row among them, or the application's own row has another domain or is detaching."
}
}
},
{
"name": "custom_domains_not_yet_served",
"surfaces": [
"management_action"
],
"status": 400,
"owner": "SVC-L0-25",
"summary": "The manifest declares a custom domain that no row of the platform's table has, while the estate's `custom_domains` setting reads 0 or its edge profile setting is empty. So the platform binds none yet. A recorded manifest's declaration is refused the same way, and a declaration that an unchanged row already has is accepted.",
"remedy": "Remove the custom_domain row from the manifest and call submit_manifest again. Nothing you do lifts the setting; the platform operator lifts it when the estate serves custom domains.",
"members": {
"hostname": {
"type": "string",
"description": "The declared hostname."
}
}
},
{
"name": "database_credential_unreadable",
"surfaces": [
"management_action"
],
"status": 502,
"owner": "DBS-L0-02",
"summary": "On deploy, promote, rollback, restart, or query_database: the application has a database, but its credential could not be read from custody. At a serverless migration step, no migration ran and the earlier version keeps serving.",
"remedy": "Retry the request. Where it repeats for development, run `turnzero provision --application <application id>` with nothing piped. Add `--origin` where your other lines include one, and make any call it prints. Its line replaces the development database credential in custody through `store_secret` with `replace: true`.\n\nWith no shell, ask the person to run that development command. Ask them to paste the printed `tzcloud_submit_manifest` call into this chat. Make it through your own connection, then ask them to run the returned line on that same computer.\n\nIf development serves a version, the provision line restarts that version; it does not deploy the refused version. Where development serves nothing, it restarts nothing; the next development deploy injects the new credential. Deploy development again with the same files, or repeat `query_database` if that was the refused call. If `database_credential_unreadable` repeats after the line succeeds, report it as for production below.\n\nOn a refused or failed deploy, promote or rollback, a version already serving stays in place. Where none was serving, nothing serves afterwards.\n\nWhere it repeats for production, nothing you do corrects it. The platform operator handles the reported fault in either environment. Call `submit_feedback` with the refusal and the refused call's `reference`, then `read_feedback` with the returned issue id.\n\nFor `deploy`, `promote` or `roll_back`, quote that call's answer's `reference`, even where a later `read_status` shows the refusal. That later read's `reference` identifies only the read.\n\nThe feedback issue's `fixed` state means built and being released. Read `note_to_reporters` and `live_in`; retry only after the platform confirms restoration or that the fix is live.\n\nSetting `rotate_database_credential: true` on a retried production deploy or promote does not repair this refusal: the platform must read the standing credential before it can rotate it."
},
{
"name": "database_move_in_flight",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "PLD-L0-63",
"summary": "An unfinished production database move refuses another database move (API-L0-31), a new production version, or application deletion (DBS-L0-08). Account erasure waits for the move and refuses if its wait ends first. The move’s own redeploy after the switch is admitted.",
"remedy": "Repeat the same request after the database move completes or is reverted."
},
{
"name": "database_not_provisioned",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "PLD-L0-63",
"summary": "deploy: the deploy goes to development, the recorded manifest declares the database kind, and the development environment has no database. That happens after delete_environment and then create_environment with no submit_manifest since, or after a submission whose database provisioning was refused. Nothing was written, and no deploy was counted toward the day's quantity.",
"remedy": "Call submit_manifest again with the same manifest, which provisions the development database, then deploy again."
},
{
"name": "database_package_outdated",
"surfaces": [
"management_action"
],
"status": 400,
"owner": "PLD-L0-63",
"summary": "deploy and deploy_files, including check_only: the recorded manifest lists Database below 0.14.0, or a library copy in the zip gives a version below 0.14.0. A copy is identified by its turnzero.entry; an ordinary package with no entry is ignored. An unreadable library copy, entry or version also refuses where the environment declares or holds a database. The manifest row is checked before an upload grant or file upload; check_deploy reports that row alone, since it reads no zip. Unlimited applications are exempt. Nothing was written: no version row, counted deploy or build.",
"remedy": "If the copy is unreadable, restore its complete `package.json` before retrying. For an older Database copy, take version 0.14.0 or later from the library and replace the copy under `lib/`. Call `submit_manifest` with the regenerated `packages` rows, then deploy again. If the `deploy_files` list leaves the copy out for the platform to fill, instead set Database's `packages` row to the version the library serves, 0.14.0 or later. Keep its root `package.json` `file:` dependency, call `submit_manifest` with the updated manifest, and send the file list again. Changing the row alone cannot update a copy you send."
},
{
"name": "database_provisioning_failed",
"surfaces": [
"management_action"
],
"status": 502,
"owner": "PLD-L0-80",
"summary": "On submit_manifest: provisioning the database role or password for the declared database kind failed. On store_secret with replace: true: the development database is recorded but its role is missing, so nothing was changed. Either failure is recorded on the platform side under a reference the detail gives, and the detail never repeats the error's own message.",
"remedy": "After submit_manifest, call it again with the same manifest: a retry completes the partial provisioning run. Where the detail says a deletion ended the run, submit again only once no deletion is under way. If the refusal repeats, report it and quote the reference its detail gives. After store_secret with replace: true, call delete_environment on development: it removes the database, on one environment or two, together with the secrets, files, and logs kept at the development scope. Then submit_manifest sets it up again with a new database, with create_environment before it on two environments. If that deletion fails, report it and quote the reference its detail gives."
},
{
"name": "database_size_not_open",
"surfaces": [
"management_action"
],
"status": 403,
"owner": "API-L0-31",
"summary": "The requested dedicated database size is not available on this estate, or is not open to this billed account under `dedicated-database-sizes`. The detail lists the dedicated sizes open to the account, or says none are open. No pending action or database move is created; production keeps its current size.",
"remedy": "Choose a dedicated size the detail lists. If none is open, leave the database as it is or ask support. This refusal does not prevent an otherwise admitted move back to `database-shared`."
},
{
"name": "database_size_unread",
"surfaces": [
"management_action"
],
"status": 503,
"owner": "API-L0-31",
"summary": "The production database's size could not be read while `set_database_size` has a size bound to check. The detail gives that bound in bytes. No pending action or database move is created. Production keeps its current size.",
"remedy": "Repeat `set_database_size` in a few minutes. If the refusal repeats, report it with its detail."
},
{
"name": "database_too_large_to_move",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "API-L0-31",
"summary": "The production database holds more bytes than `set_database_size` admits for a move. The detail gives its bytes and the move bound. No pending action or database move is created; production keeps its current size.",
"remedy": "Ask support for the operator to move the database with `database-move` at a time agreed with you."
},
{
"name": "declared_audience_contradicts_route",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "ADM-L0-05",
"summary": "submit_manifest: the manifest declares the invited audience while an existing realm's sign-in methods include the work-account route, entra, which an invitation-only realm refuses.",
"remedy": "Call configure_app_sign_in for each realm whose sign-in methods include entra, giving sign_in_methods without it, then call submit_manifest again. Or keep the audience the recorded manifest declares.",
"members": {
"audience": {
"type": "string",
"description": "The audience the submitted manifest declares, invited at this refusal."
},
"environment": {
"type": "string",
"description": "The environment whose existing realm's sign-in methods include the work-account route, development or production, the first one found."
},
"sign_in_methods": {
"type": "array",
"items": {
"type": "string"
},
"description": "The sign-in methods that realm is configured with, the work-account route entra among them."
}
}
},
{
"name": "declared_tenant_contradicts_route",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "ADM-L0-05",
"summary": "submit_manifest: the manifest's workforce audience gives an Entra tenant other than the one an existing realm's work-account route is configured against, in either environment's realm.",
"remedy": "Call configure_app_sign_in for the environment the refusal gives, with the tenant the manifest declares, or change the manifest's workforce tenant to the one the route is configured against. Then call submit_manifest again.",
"members": {
"tenant": {
"type": "string",
"description": "The Entra tenant the submitted manifest declares under the workforce audience."
},
"configured_tenant": {
"type": "string",
"description": "The Entra tenant the work-account route of that environment's realm is configured against."
},
"environment": {
"type": "string",
"description": "The environment whose existing realm's work-account route is configured against another tenant, development or production, the first one found."
}
}
},
{
"name": "dedicated_capacity",
"surfaces": [
"management_action"
],
"status": 503,
"owner": "API-L0-31",
"summary": "The platform has no room for a dedicated database move. One of three bounds is reached: the cell's dedicated servers, the region's cores, or the moves in flight. No pending action or database move is created. Production keeps its current database size.",
"remedy": "Repeat the request after the operator makes room. At the concurrent-move bound, repeat after a move ends."
},
{
"name": "deletion_in_progress",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "PLD-L0-66",
"summary": "A deletion of the application, or of one of its environments, is in progress. Every action whose request gives the application refuses with this name, with these exceptions: reads other than `check_deploy` and `check_manifest`; `read_approval_status`; `delete_application`; and `delete_environment` on the environment whose own row has the deletion marker. A failed deletion walk is retried by the same deletion action, and the marker clears when the walk completes.",
"remedy": "Wait for the deletion to finish, watching it through list_applications or read_approval_status. Then repeat your request, but only if the development environment alone was deleted, since a deleted application no longer exists. If the deletion failed, run the same delete_application or delete_environment on the same subject again to complete it. A deletion approved while another deletion of the same application is in progress ends failed with this refusal. That refusal's detail gives the instant the other deletion's hold lapses; if its process stopped, request your deletion again after that instant. An account deletion that stopped this way, before its first member, gives the application and the instant its hold lapses. Request the account deletion again once that deletion ends."
},
{
"name": "deploy_area_unavailable",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "PLD-L0-86",
"summary": "deploy's preparing call and deploy_files: a storage area your account declared exists under the name of the application's deploy area, `deploy-<application id>`, without the platform's marker. So no upload can be prepared and no file kept there. The existing area is left as it is.",
"remedy": "Deploy with `artifact` from an area of your own, uploaded under a grant from mint_upload_grant. The existing area and its files are the account's own, and a deploy leaves them untouched."
},
{
"name": "deploy_failed",
"surfaces": [
"management_action"
],
"status": null,
"owner": "PLD-L0-90",
"summary": "On deploy: a run the registry did not schedule, or a function build whose bounds, pushed artifact or layer the platform could not read as required (FNS-L0-05). Most often the build was refused before it started because the platform's base image could not be read. Nothing was built or applied, and the serving version is untouched. The history row ends failed with this outcome, its detail the refusal's text, with no `build` member.",
"remedy": "Read the failed row's outcome through read_status or list_versions. Where its detail says a retry may go through, deploy again. Where it says the platform has recorded it, nothing in the artifact needs to change, and a deploy goes through once the platform restores the image."
},
{
"name": "deploy_files_hash_mismatch",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "MAPI-26",
"summary": "A `deploy_files` file call, a list entry with `content`, or a list entry with `stored` gave a `sha256` that the file's bytes do not have, decoded where `encoding` is `base64`. The detail gives the path or the entry, the hash received, and, for sent content, the common causes: line endings, a trailing newline, or a byte-order mark. A file call's detail also gives the hash given. A file call keeps nothing, and a stored entry's file is not kept. A list keeps each other entry that passed its checks; `kept` lists those and each entry by `sha256` alone whose file the platform holds and could read as the refusal was built, and `refused` each refused entry. A binary file goes as base64 with `encoding` `base64`. The deploy line's own refusal of a whole zip is `upload_hash_mismatch`.",
"remedy": "Send the list again, giving each `kept` file by its `sha256`. For a stored entry, check the area and name; give the hash of the stored bytes or omit `sha256`. For inline content, correct the hash or omit it, or send that file first as `file`. Send binary content as base64 with `encoding` `base64`. An inline file over 512 KiB can use a stored entry. Beyond 4 MiB total or 200 entries, use the command or ZIP upload route.",
"members": {
"kept": {
"type": "array",
"description": "On a `deploy_files` list whose content entries are refused one by one, each content entry kept and each entry by `sha256` alone whose file the platform holds and could read as the refusal was built, in the list's order. Files that passed, and those earlier calls kept, are held now, and a retry gives each by its `sha256`.",
"items": {
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "The entry's path, as the list gave it."
},
"sha256": {
"type": "string",
"description": "The SHA-256 the platform computed over the content it received, the hash a retry gives."
}
}
}
},
"refused": {
"type": "array",
"description": "On a `deploy_files` list whose content entries are refused one by one, each refused entry, in the list's order. The list is never empty, and its first entry is the one the detail cites.",
"items": {
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "The entry's path, as the list gave it."
},
"error": {
"type": "string",
"description": "The refusal name the entry met."
},
"received_sha256": {
"type": "string",
"description": "With `deploy_files_hash_mismatch`: the SHA-256 the platform computed over the bytes it received or read, which the hash the call gave did not match."
}
}
}
}
}
},
{
"name": "deploy_files_syntax_error",
"surfaces": [
"management_action"
],
"status": 422,
"owner": "MAPI-26",
"summary": "A `deploy_files` file, a `.json` file or a JavaScript or TypeScript one, does not parse. The detail gives the path, the line, the column, and the parser's reason in a fixed sentence, or `Babel reason` and the reason's code where no sentence is written for it. It quotes no text of the file. Where the call sent the file's text and room allows, it also gives up to three characters a reader cannot see on that line, nearest first, by code point and column, such as `U+2028 at column 19`, and counts any others. Where room allows, it then says the line was read after the call's JSON was decoded, so a `\\u` escape the call carried arrives as the character itself. A file call keeps nothing for it, and a list call starts nothing. A list keeps each other content entry that passed its checks; `kept` lists those and each entry by `sha256` alone whose file the platform holds and could read as the refusal was built, and `refused` each refused entry.",
"remedy": "Fix the file at the line and column the detail gives, and send the list again. To send the six literal characters `\\u2028` or `\\u2029` in `content`, double the backslash in the call's JSON: `\\\\u2028` or `\\\\u2029`; otherwise JSON decodes the escape to the character itself. Send each `kept` file by its `sha256` and each `refused` file with its corrected `content`, or send that file first as `file`.",
"members": {
"kept": {
"type": "array",
"description": "On a `deploy_files` list whose content entries are refused one by one, each content entry kept and each entry by `sha256` alone whose file the platform holds and could read as the refusal was built, in the list's order. Files that passed, and those earlier calls kept, are held now, and a retry gives each by its `sha256`.",
"items": {
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "The entry's path, as the list gave it."
},
"sha256": {
"type": "string",
"description": "The SHA-256 the platform computed over the content it received, the hash a retry gives."
}
}
}
},
"refused": {
"type": "array",
"description": "On a `deploy_files` list whose content entries are refused one by one, each refused entry, in the list's order. The list is never empty, and its first entry is the one the detail cites.",
"items": {
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "The entry's path, as the list gave it."
},
"error": {
"type": "string",
"description": "The refusal name the entry met."
},
"received_sha256": {
"type": "string",
"description": "With `deploy_files_hash_mismatch`: the SHA-256 the platform computed over the content it received, which the hash the call gave did not match."
}
}
}
}
}
},
{
"name": "deploy_files_too_large",
"surfaces": [
"management_action"
],
"status": 413,
"owner": "MAPI-26",
"summary": "A `deploy_files` call exceeded a limit: an inline file over 512 KiB, a list over 200 entries, or listed and filled files over 4 MiB total. This refusal also occurs if a stored file changes size while being read. The detail gives the sizes or entry count, and `limit` identifies the case.\n\nWhen a list entry's content exceeds 512 KiB, `kept` lists the accepted content entries and each entry given only by `sha256` whose file the platform could read when building the refusal. `refused` lists the rejected entries.",
"remedy": "If a stored file changed size while being read, send the list again. If it changes again, ask your user to upload it again.\n\nFor an inline file over 512 KiB, use a stored entry. With no shell, get the page's address from `read_status`'s `dashboard`, then ask the person to sign in there, use Upload a file and give you the stored name. Stored entries do not raise the 4 MiB total or 200-entry limits. Beyond those, use the turnzero command where it works, otherwise the ZIP upload route: `declare_storage_area` if needed, `mint_upload_grant`, upload, then `deploy` with the ZIP as `artifact`. If no available in-tool route works, give the person one exact step at a time in their own terminal; never suggest changing permissions or pasting a token into chat.",
"members": {
"limit": {
"type": "string",
"description": "`files` means over 200 entries; `file_bytes` means an inline file over 512 KiB. `total_bytes` means listed and filled files exceed 4 MiB total, or a stored file's byte count differs from its earlier metadata."
},
"kept": {
"type": "array",
"description": "On a `deploy_files` list whose content entries are refused one by one, each content entry kept and each entry by `sha256` alone whose file the platform holds and could read as the refusal was built, in the list's order. Files that passed, and those earlier calls kept, are held now, and a retry gives each by its `sha256`.",
"items": {
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "The entry's path, as the list gave it."
},
"sha256": {
"type": "string",
"description": "The SHA-256 the platform computed over the content it received, the hash a retry gives."
}
}
}
},
"refused": {
"type": "array",
"description": "On a `deploy_files` list whose content entries are refused one by one, each refused entry, in the list's order. The list is never empty, and its first entry is the one the detail cites.",
"items": {
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "The entry's path, as the list gave it."
},
"error": {
"type": "string",
"description": "The refusal name the entry met."
},
"received_sha256": {
"type": "string",
"description": "With `deploy_files_hash_mismatch`: the SHA-256 the platform computed over the content it received, which the hash the call gave did not match."
}
}
}
}
}
},
{
"name": "deploy_in_flight",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "PLD-L0-63",
"summary": "The environment already has a version-history row in flight. This refuses deploy, promote, roll_back, restart_application, halt_environment, clear_development_database, and a change of size or sleep setting by set_app_size, or the operator's placement, that changes production's group or grain or writes its replica floor in place. For a deploy with `artifact`, the in-flight row is a deploy whose artifact hash differs from this request's. A request with the in-flight hash returns that deploy's answer instead. For a deploy with `upload`, the in-flight row did not read that upload. Another upload is refused even where its bytes are identical, and the same upload returns that deploy's answer instead (PLD-L0-86).\n\nA `restart` in flight (the re-creation of the serving compute under current settings by `restart_application`, a rename, or the platform) refuses a deploy whatever its hash (PLD-L0-84). A deploy to production is refused the same way while a rollback or a promote of production is in flight (PLD-L0-43; PLD-L0-96). For a promote or a rollback, a production row of any kind is in flight, and read_status or list_versions shows when it ends. For a restart_application, a row of the environment of any kind is in flight, and the restart can run once it ends (PLD-L0-84). A halt is refused while a deploy, promote, or restart of the environment is in flight. A development database clear is refused while a development deploy or restart is in flight.\n\nEither can run once that row ends (PLD-L0-41; DBS-L0-10). A halt of production while a production deploy is still building its image can run instead, and it ends that deploy. Past the build, the halt is refused until the deploy ends (PLD-L0-41).\n\nA read_logs call with source \"container\" on an environment without compute is also refused with this name where a version is in flight there. It is refused likewise where the environment has no unretired history row, is the deploy target, and read_status reports an upload in upload_in_progress (PLD-L0-86).",
"remedy": "Watch read_status or list_versions until the in-flight deploy, promote, or restart ends, then repeat the request. To follow a deploy already in flight, repeat the deploy with the same artifact or with the same upload. For a read_logs container read, follow read_status with wait_seconds through the upload or run, then repeat the read. If read_status returns pending_upload, read its refusal and retry members."
},
{
"name": "deploy_seam_absent",
"surfaces": [
"management_action"
],
"status": 503,
"owner": "PLD-L0-136",
"summary": "A hosting cell is registered, but the control plane has no live provider seam bound to apply compute through. The actions deploy, deploy_files, promote, roll_back, and restart_application refuse with it, and a change of size or sleep setting by set_app_size, or the operator's placement, does where it sets a placed container's replica floor in place. So does read_logs on the `container` source, where the environment runs as a pod and the control plane binds no Kubernetes seam.",
"remedy": "Nothing you do corrects this. The platform operator binds the provider seam on the control plane, so report the refusal with its detail."
},
{
"name": "deploys_per_day_exceeded",
"surfaces": [
"management_action"
],
"status": 429,
"owner": "PLD-L0-63",
"summary": "On deploy: the application's deploys started within the last 24 hours reach its size's `deploys-per-day` quantity, served from the pricing registry (PRC-L0-16). The next deploy can run once the oldest of them is older than 24 hours. A promote is not a deploy.",
"remedy": "Wait until the application's oldest deploy of the last 24 hours is more than 24 hours old, then deploy again. On an application with two environments, you can still promote an already-built version in the meantime."
},
{
"name": "description_changed",
"surfaces": [
"management_action"
],
"status": null,
"owner": "API-L0-07",
"summary": "A pending action records this outcome when the platform describes the subject again at approval and that description differs from the one you approved. A description that is refused by name counts as changed. The record ends declined, and nothing runs. The outcome gives `description`, the one approved, and `current_description`. Read it through read_approval_status.",
"remedy": "Compare the description you approved with the current one, on the approval page or through read_approval_status. Where the act is still wanted, request it again and approve the current description in the browser."
},
{
"name": "destructive_class_required",
"surfaces": [
"management_action"
],
"status": 403,
"owner": "MAPI-12",
"summary": "You made a destructive-tier request from a credential that has no destructive class, so no pending action is created.",
"remedy": "Repeat the action from your tool's connected session, the one your own sign-in opened. Alternatively, from that session call mint_token with the destructive grant, then repeat the action under the new token."
},
{
"name": "development_estate_required",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "MAPI-27",
"summary": "A staff purge of development applications reached an estate other than development. The plane reads its role from its public origin, and only the development estate deletes applications with no pending action. Nothing was read and nothing was deleted.",
"remedy": "Run the purge on the development estate. On this estate, delete each application through delete_application and its browser approval."
},
{
"name": "development_realm_full",
"surfaces": [
"realm_surface"
],
"status": 403,
"owner": "ACS-L0-12",
"summary": "A sign-in would create a new end-user account in a development realm that already has the served `development-realm-account-limit` for its size, ten. Nothing is created, and an existing account still signs in. The production realm has no such cap.",
"remedy": "Sign in with an account that already exists in the development realm. Or, if you are the application's author, delete one of its end users with delete_end_user, giving the development environment. Only the platform's operator raises the limit."
},
{
"name": "device_sign_in_bounded",
"surfaces": [
"management_action"
],
"status": 403,
"owner": "MAPI-16",
"summary": "An action outside the bound of the `device_sign_in` grant, reached under a session the device grant issued for the Turn Zero server itself. Such a session reaches the rows whose admits mark lists the grant, the anonymous rows, and the forwarded tzMesh and tzTrack rows, and no other row of the account; it holds no super_admin even for an operator. The refusal gives the grant and the rows the bound allows.",
"remedy": "Call the action from a browser sign-in, or under a token minted from one; a session the device grant issued is for the products and its own rows alone, and mint_token refuses it.",
"members": {
"grant": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]*$",
"description": "The grant that bounds the credential, device_sign_in."
},
"admitted": {
"type": "array",
"items": {
"type": "string"
},
"description": "The rows the bound admits on this plane, the grant's own rows and those whose admits mark lists it."
}
}
},
{
"name": "differing_redeclaration",
"surfaces": [
"management_action",
"storage"
],
"status": 409,
"owner": "OST-L0-01",
"summary": "You declared an area again with declarations that differ from the existing ones.",
"remedy": "Send the declaration again with the existing declarations the refusal lists. To use different declarations, declare a new area under another name with declare_storage_area and move the files into it. Or, where the area has no file, remove it with declare_storage_area and remove true, and declare the name again."
},
{
"name": "egress_connect_failed",
"surfaces": [
"egress_tunnel"
],
"status": 502,
"owner": "EGW-L0-16",
"summary": "The tunnel proxy dialled the address it resolved for your target, and the connection was not accepted.",
"remedy": "Retry the request. If the refusal repeats, report it with its detail."
},
{
"name": "egress_connections_capped",
"surfaces": [
"egress_tunnel"
],
"status": 429,
"owner": "EGW-L0-18",
"summary": "The tunnel proxy refused a new outbound connection. Your application opened more connections in this UTC minute through this proxy replica than its size's quantity allows. Both sizes have the same quantity. The body gives count, limit, and resets_at, the instant the minute ends. Connections already open keep running.",
"remedy": "Wait for the next UTC minute, then connect again. Reuse connections instead of opening one per request. A larger size does not raise it."
},
{
"name": "egress_daily_bytes_capped",
"surfaces": [
"egress",
"egress_tunnel"
],
"status": 429,
"owner": "EGW-L0-18",
"summary": "Your application has moved more bytes today, in UTC, through outbound connections and calls to its own upstreams than its size's quantity allows. Both sizes have the same quantity. The tunnel proxy refuses new connections and cuts open ones at their next byte, recording the cut as refused_bounds. The gateway refuses calls to the application's own declared upstreams. The body gives the day's bytes as count, the limit, and resets_at, the first instant of the next UTC day.",
"remedy": "Wait for the instant resets_at gives, the start of the next UTC day, then try again. Read today's bytes and the limit in read_usage's egress_limits member. A larger size does not raise it."
},
{
"name": "egress_key_not_admitted",
"surfaces": [
"management_action",
"mcp_server",
"storage",
"egress",
"egress_tunnel",
"logging",
"documentation",
"realm_surface",
"push",
"email"
],
"status": null,
"owner": "SEC-L0-18",
"summary": "The egress key the platform mints for one upstream of one deployed compute works only on that upstream's keyed route. Everywhere else it is refused with this name (403): another upstream, a management action, the storage and logging routes, a gated documentation tree's machine files, the push send route, and the realm surface. The MCP server refuses it with a 401 challenge, and the tunnel seat with 407.",
"remedy": "Present the egress key only as the bearer of calls under the base URL in its setting, which the deploy set for that upstream. To call another upstream the same way, declare it with its own `sdk_settings` and read that upstream's key setting. For any other act, present the credential that surface accepts, such as the application's platform credential on the storage and logging routes.",
"members": {
"credential_kind": {
"type": "string",
"description": "The kind of the credential refused, egress_key at this refusal."
}
}
},
{
"name": "egress_link_local_address",
"surfaces": [
"egress",
"egress_tunnel"
],
"status": 403,
"owner": "EGW-L0-13",
"summary": "At the tunnel proxy, the target is, or its name resolved to, a link-local address when the connection is set up, the instance metadata address among them. At the egress gateway, at each call, the declared upstream's host resolved to a link-local address (EGW-L0-01).",
"remedy": "Send the request to a host name that resolves to a public unicast address, and make each redirect it follows do the same. Declaring the name does not allow a link-local address. For a declared upstream, run declare_outbound_api again under the same upstream name with a base URL whose host resolves to public unicast addresses alone. Include the upstream's `sdk_settings` in that call, or omit the member, which keeps them; `sdk_settings` null removes them and ends the upstream's egress keys."
},
{
"name": "egress_loopback_address",
"surfaces": [
"egress",
"egress_tunnel"
],
"status": 403,
"owner": "EGW-L0-13",
"summary": "At the tunnel proxy, the target is, or its name resolved to, a loopback address when the connection is set up. At the egress gateway, at each call, the declared upstream's host resolved to a loopback address (EGW-L0-01).",
"remedy": "Send the request to a host name that resolves to a public unicast address, and make each redirect it follows do the same. Declaring the name does not allow a loopback address. For a declared upstream, run declare_outbound_api again under the same upstream name with a base URL whose host resolves to public unicast addresses alone. Include the upstream's `sdk_settings` in that call, or omit the member, which keeps them; `sdk_settings` null removes them and ends the upstream's egress keys."
},
{
"name": "egress_platform_address",
"surfaces": [
"egress",
"egress_tunnel"
],
"status": 403,
"owner": "EGW-L0-15",
"summary": "At the tunnel proxy, the target is a platform endpoint by name, or is, or its name resolved to, an address in the platform's own range; no tunnel reaches it. At the egress gateway, at each call, the declared upstream's host resolved to an address in the platform's own range (EGW-L0-01).",
"remedy": "Call that endpoint directly, with no proxy agent on the request, and do not add it to your manifest's egress list. Where your manifest does not declare the service that provides it, add the service with submit_manifest, then deploy. For a declared upstream, run declare_outbound_api again under the same upstream name with a base URL whose host resolves to public unicast addresses alone; no declared upstream reaches the platform's own range. Include the upstream's `sdk_settings` in that call, or omit the member, which keeps them; `sdk_settings` null removes them and ends the upstream's egress keys."
},
{
"name": "egress_port_refused",
"surfaces": [
"egress_tunnel"
],
"status": 403,
"owner": "EGW-L0-12",
"summary": "The tunnel proxy refuses a CONNECT request to any port other than 443, and every forward HTTP request. This applies in observe and enforce modes. An accepted CONNECT tunnel passes bytes through without inspecting TLS or HTTP.",
"remedy": "Open a CONNECT tunnel to the destination on port 443, and configure your client to use CONNECT instead of forward HTTP requests. Where the destination accepts only another port, nothing you do corrects this, because only the platform can allow another port. Ports 25, 465, 587, and 2525 are outbound mail ports. Applications send no mail directly. Send mail through a mail provider's HTTPS API, declared as an upstream."
},
{
"name": "egress_private_address",
"surfaces": [
"egress",
"egress_tunnel"
],
"status": 403,
"owner": "EGW-L0-13",
"summary": "At the tunnel proxy, the target is, or its name resolved to, a private address when the connection is set up. At the egress gateway, at each call, the declared upstream's host resolved to a private address (EGW-L0-01).",
"remedy": "Send the request to a host name that resolves to a public unicast address, and make each redirect it follows do the same. Declaring the name does not allow a private address. For a declared upstream, run declare_outbound_api again under the same upstream name with a base URL whose host resolves to public unicast addresses alone. Include the upstream's `sdk_settings` in that call, or omit the member, which keeps them; `sdk_settings` null removes them and ends the upstream's egress keys."
},
{
"name": "egress_reserved_address",
"surfaces": [
"egress",
"egress_tunnel"
],
"status": 403,
"owner": "EGW-L0-13",
"summary": "At the tunnel proxy, the target is, or its name resolved to, a reserved, unspecified, documentation, benchmarking, or multicast address when the connection is set up. At the egress gateway, at each call, the declared upstream's host resolved to an address in a reserved range (EGW-L0-01).",
"remedy": "Send the request to a host name that resolves to a public unicast address, and make each redirect it follows do the same. Declaring the name does not allow an address in a reserved range. For a declared upstream, run declare_outbound_api again under the same upstream name with a base URL whose host resolves to public unicast addresses alone. Include the upstream's `sdk_settings` in that call, or omit the member, which keeps them; `sdk_settings` null removes them and ends the upstream's egress keys."
},
{
"name": "egress_resolve_unavailable",
"surfaces": [
"egress_tunnel"
],
"status": 503,
"owner": "EGW-L0-16",
"summary": "The tunnel proxy could not check the connection. The control plane did not respond to its read of your application's declarations, and it has no earlier response for the credential, or that response is past the proxy's maximum age. The connection is refused instead of being accepted unchecked.",
"remedy": "Retry the connection after a short wait. The refusal ends when the platform's control plane responds to the tunnel proxy again; you need to change nothing."
},
{
"name": "egress_undeclared",
"surfaces": [
"egress_tunnel"
],
"status": 403,
"owner": "EGW-L0-14",
"summary": "In enforce mode, the tunnel proxy refused a target host that the manifest's `egress` list does not declare. The body gives the host, the port, and the remedy. For a hostname, the remedy is the exact manifest edit. For an address literal, the remedy says that no address literal can be declared (MAN-09). It tells you to declare the hostname the address serves instead. In observe mode the connection goes ahead where it passes the other checks, and this name is written only to the egress record's observed row, never sent to you. An address literal in a refused class is refused by its class in both modes, before this check (EGW-L0-13).",
"remedy": "Add the refused hostname to the manifest's egress list and redeploy. Where the refused host is an address literal, declare the hostname the address serves instead, and redeploy."
},
{
"name": "egress_unresolvable",
"surfaces": [
"egress_tunnel"
],
"status": 403,
"owner": "EGW-L0-13",
"summary": "The tunnel proxy could not resolve the CONNECT target: it is not in host:port form, or the name resolved to no address.",
"remedy": "Write the CONNECT target as host:port, with a host name that resolves at request time to a public unicast address."
},
{
"name": "email_domain_undeliverable",
"surfaces": [
"realm_surface",
"builder_sign_in",
"management_action"
],
"status": 400,
"owner": "ACS-L0-19",
"summary": "The address's domain has no mail server: it does not exist, it publishes a null MX, or it publishes no MX and no A or AAAA record with a public address. The platform checks before an emailed-code start outside the fixture domain, and before the application-less form of invitation's issue act, the one form that sends. Nothing was sent, no code is pending, and no invitation was issued.",
"remedy": "Check the address for a typo and try again with the corrected address. On a sign-in page, another sign-in method also works. For a builder invitation, issue it to an address whose domain accepts mail."
},
{
"name": "email_limit_reached",
"surfaces": [
"email",
"account_mail"
],
"status": 429,
"owner": "EML-L0-03",
"summary": "A send would take your application's recipients past its size's quantity for the UTC hour or the UTC day, both environments counted together. The body gives period, used, quota, requested, and resets_at, the first instant of the next period. Nothing was queued, and the counts are unchanged.",
"remedy": "Wait for the instant resets_at gives, then send again. For more volume, send through your own provider key on a declared egress upstream."
},
{
"name": "email_not_declared",
"surfaces": [
"email",
"account_mail"
],
"status": 409,
"owner": "EML-L0-01",
"summary": "Your application sent email, but its recorded manifest declares no email service. Nothing was queued.",
"remedy": "Add {\"kind\": \"email\"} to the manifest's services and resubmit it with submit_manifest, then send again."
},
{
"name": "end_user_credential_not_admitted",
"surfaces": [
"management_action",
"mcp_server",
"storage",
"egress",
"realm_surface",
"logging",
"push",
"email"
],
"status": null,
"owner": "ACS-L0-05",
"summary": "The end-user credential the accounts service issues is refused with this name on every surface except its own realm (403; a 401 challenge at the MCP server).",
"remedy": "For a management action or the MCP server, sign in as the account through your tool or use a minted token, and on the storage, logging, and egress surfaces send the application's platform credential. At the verification route, present the application's platform credential as the bearer and put the end-user session's value in the body, and act as the end user only on the realm's own account routes.",
"members": {
"credential_kind": {
"type": "string",
"description": "The kind of the credential refused, end_user at this refusal."
}
}
},
{
"name": "entitlement_apply_failed",
"surfaces": [
"management_action"
],
"status": 502,
"owner": "ACB-L0-22",
"summary": "On set_app_size: the size's entitlement could not be applied. That entitlement is the replica floor on the placed application's container app, or the role's connection limit on its provisioned database (PLD-L0-63; DBS-L0-04). The detail says which, with its value and, for the connection limit, the environment's role. The provider's or the driver's own message is recorded on the platform side under a reference the detail gives, and is never returned. The size remains as it was, and the retry is the same set_app_size.",
"remedy": "Call set_app_size again with the same size. If the refusal repeats, report it and quote the reference its detail gives. The platform corrects the failure, and the same set_app_size is the retry after that."
},
{
"name": "environment_halted",
"surfaces": [
"router"
],
"status": 503,
"owner": "SVC-L0-07",
"summary": "The serving router refuses with this on every path of a halted environment's hostname, the reserved prefix included. You or the platform halted the environment (PLD-L0-41). Calling `halt_environment` with `resume: true` on the management surface ends the halt.",
"remedy": "Call halt_environment with resume: true for the application and the environment, or deploy a version to the development environment, which ends its halt. An end user asks the application's author to do so. The refusal ends within the router's bounded interval after the resume."
},
{
"name": "environment_mismatch",
"surfaces": [
"storage",
"egress",
"logging",
"realm_surface",
"push",
"email",
"account_mail"
],
"status": 403,
"owner": "API-L0-17",
"summary": "The credential fixes the request's environment, and the request gave another one. A platform credential fixes its bound environment, a transfer grant the one it was minted in, and an egress key its own on the keyed route. The other environment came in the x-turnzero-cloud-environment header, or in the body member environment on a log batch or the verification route. Under any other credential, the header and that body member gave different environments.",
"remedy": "Make the x-turnzero-cloud-environment header and the body member environment, where you send them, agree with each other and with the credential's bound environment. To reach the other environment, present that environment's platform credential, or a minted token with that environment in the header, or in the body member environment on a log batch."
},
{
"name": "environment_never_deployed",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "PLD-L0-41",
"summary": "The environment has no deployed version, so there is nothing to act on. halt_environment refuses with it because there is nothing to halt (PLD-L0-41). restart_application refuses with it where the environment has no serving version with compute to re-create (PLD-L0-84).",
"remedy": "No further act is needed on an environment that has never been deployed. To halt or restart this environment later, first put a version on it with deploy or promote, then call halt_environment or restart_application again."
},
{
"name": "environment_not_created",
"surfaces": [
"management_action",
"realm_surface"
],
"status": 409,
"owner": "PLD-L0-96",
"summary": "The call gives an environment the application does not have. A new application has one environment, production, so an act on development is refused. So is `promote`, which needs a development environment to promote from. The exception is `delete_environment`, which is accepted and removes what is left. That applies where a development database setup exists, whole or stopped partway, or a deletion of it stopped, or where an earlier revision left a development realm or hosted placement.",
"remedy": "Pass production, or call create_environment for the application to add the development environment; a deploy then goes to development, and promote moves a version to production. To put an earlier production version back without a second environment, call roll_back."
},
{
"name": "environment_required",
"surfaces": [
"storage",
"egress",
"realm_surface",
"push",
"email"
],
"status": 400,
"owner": "API-L0-17",
"summary": "A session or a minted token, account-wide or bounded to the application, gave no environment, or a value other than development or production. On a file route, the file list, the grant mint, or a keyed egress call, the environment goes in the x-turnzero-cloud-environment header. On the verification route, it goes in that header or in the body member environment.",
"remedy": "Send the request again with the x-turnzero-cloud-environment header giving the environment, development or production. On the verification route, the body member environment works in place of the header."
},
{
"name": "environment_unavailable",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "PLD-L0-63",
"summary": "deploy: the call gave `production` on an application with two environments, where a deploy goes to development and a version reaches production through `promote` alone (PLD-L0-43; PLD-L0-96). On an application with one environment a deploy goes to production itself.",
"remedy": "Deploy to the development environment, or pass no environment, then promote the resulting version to production."
},
{
"name": "environment_undeclared",
"surfaces": [
"logging"
],
"status": 400,
"owner": "LGS-01",
"summary": "The batch's environment member is missing, or is not development, production, or local.",
"remedy": "Set the batch's environment member to development, production, or local, then send the batch again."
},
{
"name": "environment_unsupported",
"surfaces": [
"management_action"
],
"status": 400,
"owner": "MAN-06",
"summary": "On submit_manifest: the manifest has an environments member. An application's environments are set by create_environment and delete_environment, never by its manifest, which declares none.",
"remedy": "Remove the environments member from the manifest, then call submit_manifest again. One manifest text serves every environment the application has, so add no replacement declaration."
},
{
"name": "erasure_ticket_refused",
"surfaces": [
"realm_surface"
],
"status": 403,
"owner": "ACB-L0-47",
"summary": "The accounts service's erase-token route received no live erasure ticket for the account: the ticket is missing, spent, expired, or for another account.",
"remedy": "Nothing you call corrects this. Only the account's erasure walk presents a ticket, and the walk retries."
},
{
"name": "execution_failed",
"surfaces": [
"management_action"
],
"status": null,
"owner": "PLD-L0-80",
"summary": "A pending action records this failure when its handler threw something other than a refusal by name, or when its description threw at approval. Read it through read_approval_status. The failure is recorded on the platform side under a reference the detail gives, and the detail never repeats the error's own message. A deletion walk's failure also gives the member the walk stopped at, beside the receipts written before it (PLD-L0-66).",
"remedy": "Read the outcome through read_approval_status and check the current state, then request the action again where it is still wanted. The new request creates a new pending action that needs browser approval, and a repeated deletion runs its walk again, reporting zero removals for what is already gone."
},
{
"name": "expired_token",
"surfaces": [
"builder_sign_in"
],
"status": 400,
"owner": "MCP-02",
"summary": "The device code's ten minutes passed, whether or not you allowed the request (RFC 8628). The request is deleted and no token is issued.",
"remedy": "Start the sign-in again with a new device authorization request."
},
{
"name": "export_not_completed",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "API-L0-23",
"summary": "On request_export with download: true: the export the call gives has not completed, so no download grant is minted for it. It is still running, or it failed; a running export whose heartbeat went stale counts as failed.",
"remedy": "For a running export, read it with read_export until its state is completed, then call request_export with download: true again. For a failed one, call request_export again for the application and the environment, read the new export until it is completed, and pass its id."
},
{
"name": "feedback_queue_bounded",
"surfaces": [
"management_action"
],
"status": 403,
"owner": "MAPI-16",
"summary": "You reached an action outside the bound with a minted token that has the feedback_queue grant and no super_admin. The grant limits its token to read_feedback and settle_feedback, whose `admits` marks list it, and each handler checks the grant. The rows marked access: anonymous are outside the bound and serve the token as they serve every connection.",
"remedy": "Call the action from the owner's signed-in session, or under a token minted through mint_token without the feedback_queue grant. The refusal's `admitted` member lists the actions the bounded token can reach.",
"members": {
"grant": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]*$",
"description": "The grant that bounds the credential presented."
},
"admitted": {
"type": "array",
"items": {
"type": "string"
},
"description": "The actions the bound admits, in the enumeration's order: the rows the grant marks and the rows whose admits mark lists it. The rows marked access: anonymous lie outside the bound and are not listed."
}
}
},
{
"name": "feedback_rate_limited",
"surfaces": [
"management_action"
],
"status": 429,
"owner": "MAPI-18",
"summary": "A feedback action, a recorded check, relay_issue_act, create_space, or rename_space passed a bound. One bound is the platform's own limit on one account's filings and checks in a minute, and on its feedback reads. The others are the platform's cap on all accounts together, one token's relayed calls in a minute, and the relay's share of one space's rate. They also include an account's space creations in a minute, its space renames in a minute, and the issue service's own rate on the platform's space. The detail gives which, in parentheses.",
"remedy": "Wait for the minute to turn, then repeat the request with the same key, which the service reads as a retry and never as a second report."
},
{
"name": "file_dependency_not_sent",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "MAPI-26",
"summary": "A `deploy_files` list holds no file at or under the path where the root package.json's `dependencies` declares a library copy, `@turnzero/<name>`, as a `file:` path, and the platform fills none there, so the version would lack it. The detail gives the remedy and why the platform cannot fill it. Nothing was started.",
"remedy": "List the copy's files in `files`. Or add its row to the manifest's `packages`, at the version the library serves, and call submit_manifest, so the platform fills it. A copy declared outside the folder, or under a name a deploy leaves out, moves into the folder first."
},
{
"name": "fixture_address_reserved",
"surfaces": [
"realm_surface"
],
"status": 403,
"owner": "ACS-L0-20",
"summary": "A provider sign-in reached a customer's realm with an address at the reserved fixture domain synthetic.turnzero.ai, verified or not, and no unexpired test end user has that address. The domain is reserved for test fixtures, so nothing is created or joined. The refusal is a page at the provider's callback and JSON at the native ID-token exchange.",
"remedy": "Sign in with a real address. To test sign-in, create the test end user with add_test_end_users and labels, and sign it in through the emailed-code route from the realm's test sign-in page."
},
{
"name": "forward_unavailable",
"surfaces": [
"mcp_server"
],
"status": 503,
"owner": "MCP-14",
"summary": "A call of a product's tool through the one connection, a tool listed under the product's prefix, was not forwarded to the product's own MCP server, or had no reply from it in time. Either the product's tools are not served through this connection on this estate, or the connection is not a person's sign-in. Otherwise the connection's credential for the product could not be issued, the server could not be reached, or it refused the forwarded credential, and in each of these cases nothing was done. Where the server did not answer within the call's bound, ten seconds and any wait in the call, the call may have been made.",
"remedy": "Connect your tool to the product's own MCP server at the address in the detail, where every tool of the product is served directly. Where the detail says the server could not be reached, or that the credential could not be issued, call again in a short while first. Where it says the server did not answer in time, check whether the call was made before calling again, or call again with the same client_id where the tool takes one."
},
{
"name": "fresh_authentication_required",
"surfaces": [
"realm_surface",
"management_action"
],
"status": 403,
"owner": "ACS-L0-05",
"summary": "On the realm surface, an act arrived without the fresh authentication it needs (ACS-L0-05; ACS-L0-10). Removing a passkey needs an assertion made for that removal. Removing a passkey its device no longer has, reverting a passkey change, registering a passkey outside the sign-in's offer, and deleting the account each need a fresh authentication within the last five minutes. Under a native session, the deletion's fresh authentication is an authorization with prompt=login, its code exchanged at the token endpoint with the session's token as the bearer (ACS-L0-14). On a management action, a state-changing action under the browser session arrived more than the freshness window after the sign-in that created the session (WEB-L0-16). A page then shows a sign-in link.",
"remedy": "To remove a passkey, send the removal with an assertion made for that removal. For a passkey its device no longer has, a passkey change to revert, or a registration outside the sign-in's offer, reauthenticate first, then repeat within five minutes. Reauthenticate by start/<provider>?intent=reauth&return=app, by email/start with intent=reauth, or by another passkey at passkeys/reauth. To delete the account, request the deletion again right after a provider sign-in, an emailed code, or a passkey assertion made for it. On a native session, run an authorization with prompt=login, exchange its code at the token endpoint with the session's token as the bearer, then post the deletion again within five minutes. Under the browser session, follow the sign-in link the page shows, then repeat the action. The read_account action returns signed_in_at, the sign-in instant the window runs from."
},
{
"name": "function_busy",
"surfaces": [
"router"
],
"status": 429,
"owner": "FNS-L0-06",
"summary": "A function call was refused at an application or account bound on the pool replica it reached. The environment reached its limit on calls in flight or live workers, or the account reached its live-worker limit. The function did not run. detail identifies the bound. No retry time is supplied.",
"remedy": "For calls in flight, retry after a call ends. For a worker bound, retry after a worker ends. A refusal on one replica does not establish that every replica is full."
},
{
"name": "function_count_exceeded",
"surfaces": [
"management_action"
],
"status": 422,
"owner": "FNS-L0-05",
"summary": "Serverless functions are not yet available to customers. The installed tree holds more files under `functions/` than the bound on a version's functions (PRC-L0-16). Every file there counts as one function. The version failed at `image_build`; nothing was stored and the serving version is untouched.",
"remedy": "Move shared code from `functions/` into `lib/`, or remove functions, then deploy again."
},
{
"name": "function_native_module",
"surfaces": [
"management_action"
],
"status": 422,
"owner": "FNS-L0-05",
"summary": "Serverless functions are not yet available to customers. A file ending `.node` in the installed tree is a native module, which a serverless function cannot load. The version failed at `image_build`; nothing was stored and the serving version is untouched.",
"remedy": "Replace the dependency with one written in JavaScript, or use a server application for this work, then deploy again."
},
{
"name": "function_tree_link",
"surfaces": [
"management_action"
],
"status": 422,
"owner": "FNS-L0-05",
"summary": "Serverless functions are not yet available to customers. The function build refused a link that points outside the zip's root, at nothing or at a folder above itself, or the platform found a symbolic or hard link in the built tree. The version failed at `image_build`; nothing was stored and the serving version is untouched.",
"remedy": "Remove the link at the path in the detail, or the dependency that creates it, then deploy again."
},
{
"name": "function_tree_too_large",
"surfaces": [
"management_action"
],
"status": 422,
"owner": "FNS-L0-05",
"summary": "Serverless functions are not yet available to customers. The installed tree's uncompressed file bytes, dependencies included and links followed, exceed the bound on a version's installed tree (PRC-L0-16). The version failed at `image_build`; nothing was stored and the serving version is untouched.",
"remedy": "Remove unused code or dependencies, then deploy again."
},
{
"name": "function_tree_too_many_entries",
"surfaces": [
"management_action"
],
"status": 422,
"owner": "FNS-L0-05",
"summary": "Serverless functions are not yet available to customers. The installed tree has too many entries, counting files and folders together, including dependencies. This is one platform bound for every plan, outside the plan quotas. The version failed at image_build without a build member. Nothing was stored and the serving version is unchanged.",
"remedy": "Remove unused dependencies or files, then deploy again."
},
{
"name": "function_unavailable",
"surfaces": [
"router"
],
"status": 503,
"owner": "FNS-L0-06",
"summary": "The platform's function pool could not run the function on the replica reached. Its settings were absent or unreadable, its installed code could not load, its worker network was not ready, or the replica reached its own worker bound. The function did not run. This is a platform failure, separate from the application's function_busy bounds.",
"remedy": "Retry the request. If the refusal repeats, report its detail through submit_feedback with the originating call's reference where supplied."
},
{
"name": "grant_identity_fixed",
"surfaces": [
"storage"
],
"status": 400,
"owner": "OST-L0-08",
"summary": "A write under a transfer grant sent X-Acting-Identity with an identity other than the one fixed when the grant was minted.",
"remedy": "Send the write again with X-Acting-Identity giving the identity fixed at minting, or leave the header out. To act as another identity, mint a new grant for it, on the mint route or with mint_upload_grant's identity argument."
},
{
"name": "grant_minter_not_admitted",
"surfaces": [
"storage"
],
"status": 403,
"owner": "OST-L0-08",
"summary": "A credential other than the application's platform credential or an application-bounded minted token called POST /storage/v0/grants.",
"remedy": "Request the grant from the application's backend under its platform credential, or under a token minted with mint_token and bounded to that application. From your session or an account-wide token, mint an upload grant with mint_upload_grant instead."
},
{
"name": "grant_not_held",
"surfaces": [
"management_action"
],
"status": 403,
"owner": "MAPI-14",
"summary": "On mint_token: the minting session does not have the grant you asked for. The destructive and super_admin grants are given only where the session has them. The synthetic_seed_purge, synthetic_estate, publication, and feedback_queue grants are given only where the session has super_admin. The issues grant needs neither (MAPI-14).",
"remedy": "Call mint_token again without the grant in the refusal's `grant` member. No request adds a grant your session lacks. A person's browser sign-in gives a session the destructive class. Only the platform's own accounts have super_admin, and synthetic_seed_purge, synthetic_estate, publication, and feedback_queue are minted only from a session that has super_admin.",
"members": {
"grant": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]*$",
"description": "The requested grant the minting session does not itself hold."
}
}
},
{
"name": "grant_required",
"surfaces": [
"management_action"
],
"status": 403,
"owner": "MAPI-09",
"summary": "A credential the row does not accept reached a grant-marked action, and the refusal gives the row's grant (MAPI-09). A row accepts a credential that has its grant or super_admin, and one whose bounding grant the row's `admits` mark lists. The same name refuses a credential without super_admin on the application-less builder form of invitation, list_invitations, and configure_app_sign_in (MAPI-09; ACS-L0-08). On the queue form of read_feedback, and on settle_feedback's form for the platform's own space, it refuses a credential that has neither feedback_queue nor super_admin (MAPI-18). On relay_issue_act it refuses a credential with no issues grant. On a seed of synthetic accounts it refuses one with access_link from a credential without super_admin.",
"remedy": "If you meant your own application's realm, repeat invitation, list_invitations, or configure_app_sign_in with the application member set. If you meant your own submissions, repeat read_feedback without queue. For relay_issue_act, mint a token with the issues grant for the space from your signed-in session. Otherwise nothing you do corrects this. Only the platform operator reaches the action, from a session that has the grant, or with an account-scoped token minted from that session with the row's grant.",
"members": {
"grant": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]*$",
"description": "The grant the action requires and the credential does not hold."
}
}
},
{
"name": "grant_scope_refused",
"surfaces": [
"management_action"
],
"status": 403,
"owner": "MAPI-14",
"summary": "On mint_token: you asked for super_admin, or a narrow grant (synthetic_seed_purge, synthetic_estate, publication, feedback_queue, or issues), on an application-bounded token, which can have none of them (MAPI-14; API-L0-17).",
"remedy": "Call mint_token again either with the scope set to the whole account or without super_admin and the narrow grants among the requested grants.",
"members": {
"grant": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]*$",
"description": "The grant requested for an application-bounded token, which carries neither super_admin nor a narrow grant."
}
}
},
{
"name": "group_full",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "PLD-L0-127",
"summary": "The hosting cell's admitting group for the environment's kind has reached its nominal capacity. A group has one of three kinds: development, shared-0.5gb production that sleeps when idle, or shared-0.5gb production that stays up. So the environment cannot be placed on the pod grain there. This refuses deploy, deploy_files, promote, a redeploy under the placement rule, and set_app_size. The act is accepted once the capacity is raised, or once another group of that kind in the cell is admitting placements. A cell with no admitting group of that kind places a container app instead, and is never refused this way.",
"remedy": "Nothing you do corrects this. Repeat the act once the platform's operator has raised the capacity of the group, or has set another group of that kind in the cell to accept placements."
},
{
"name": "group_kind_mismatch",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "PLD-L0-127",
"summary": "The environment's placement row records a group of a different kind from its environment: a development row in a production group, or a production row in a development group. This refuses deploy, deploy_files, promote, a redeploy under the placement rule, and set_app_size. No compute act runs, and the row's group is corrected in the placement registry before the act is retried.",
"remedy": "Nothing you do corrects this. Report the refusal with its detail, and repeat the act once the platform's operator has moved the environment's placement into a group of its kind."
},
{
"name": "handoff_invalid",
"surfaces": [
"realm_surface"
],
"status": 400,
"owner": "ACS-L0-04",
"summary": "The handoff code is unknown, spent, expired, or belongs to another realm.",
"remedy": "Start the sign-in again from the application's sign-in page and let the browser follow the return to the application immediately. Do not reload or reuse a completion address."
},
{
"name": "health_gate_failed",
"surfaces": [
"management_action"
],
"status": 502,
"owner": "PLD-L0-59",
"summary": "On deploy, promote, or restart: the candidate's health path did not return 200 on three probes in a row within the deadline. So the candidate is deleted, and the serving compute and the previous version are untouched. The history row ends failed with this outcome and a gate member: the probe ledger, the last response, what responded, the candidate's state, and its console's last lines.",
"remedy": "Read the detail first: it opens with the likely cause where the gate's evidence shows one. Then read the failed row's outcome through read_status or list_versions: its gate member shows what responded, the candidate's state, and the console's last lines. Fix the health path or the startup failure, and deploy again. Where `outcome.gate.polls_200` is above zero and the candidate's state shows no restart, deploy again."
},
{
"name": "health_path_undeclared",
"surfaces": [
"management_action"
],
"status": 400,
"owner": "MAN-05",
"summary": "This manifest declares no health path where one is required. A deploy, promote or redeploy needs it for the health gate. submit_manifest and check_manifest also require it if either environment has a server, running or halted, or a server application's deploy, promote or redeploy is in flight (MAN-05).",
"remedy": "Add health to the manifest, submit it with submit_manifest, then repeat the refused action."
},
{
"name": "health_path_unserved",
"surfaces": [
"management_action"
],
"status": 400,
"owner": "PLD-L0-63",
"summary": "On deploy: this is a server's first deploy, to an environment that serves no version, and no source file in the zip mentions the recorded manifest's health path. Before any write, the deploy reads the text of the zip's source files for the path's last segment, leaving package files and documentation aside. It runs nothing, so a comment that mentions the path passes. No version row is inserted, nothing is built, and no deploy is counted. After submit_manifest the same upload starts, since a deploy runs under the recorded manifest, never the zip's manifest.json; only changed code needs a new zip.",
"remedy": "Serve the health path from the source file that handles requests, and deploy the new zip; a comment that mentions it in any source file also passes, which suits a route a dependency serves. Or set the manifest's health to a path the source serves, call submit_manifest, and deploy again; under the upload form the same upload then starts."
},
{
"name": "id_token_invalid",
"surfaces": [
"realm_surface"
],
"status": 400,
"owner": "ACS-L0-14",
"summary": "The token endpoint's token exchange received an ID token that fails verification against its issuer's published keys. Its signature, its issuer, its expiry, or its audience failed, or the client declares no audience for that issuer. A subject token that is not an Apple or Google ID token is refused the same way.",
"remedy": "Sign in again in the app so its SDK returns a fresh ID token. Declare your app's own audience on the client: its ios.bundle_id for Apple, and its Google client identifiers in google_client_ids. Declare it with configure_app_sign_in where the manifest lists no clients for that environment, or in the manifest's realm clients list for that environment, then call submit_manifest."
},
{
"name": "identity_already_bound",
"surfaces": [
"builder_sign_in",
"realm_surface"
],
"status": 409,
"owner": "ACB-L0-03",
"summary": "The sign-in you tried to link, a provider and its subject, already reaches a different account of the same realm. Nothing is linked. You meet this refusal on the page that completes a link_identity link, and at the link the platform offers when a sign-in's address matches an existing account. On an application's end-user realm, an emailed-code sign-in that joins an existing account can meet it too. It applies on the builder realm and on an end-user realm alike.",
"remedy": "Sign in with that provider identity to reach the account it already belongs to. If you meant to add a sign-in method to the account you are signed in to, link a different identity through link_identity."
},
{
"name": "identity_collision",
"surfaces": [
"realm_surface"
],
"status": 409,
"owner": "ACS-L0-14",
"summary": "The token exchange's ID token has a provider-verified address that another user of the realm already has under another route. Nothing was created and no session opened.",
"remedy": "Sign in through the browser flow with the existing account's own route, and link the two routes there. Either route then reaches the one account."
},
{
"name": "identity_required",
"surfaces": [
"storage"
],
"status": 400,
"owner": "OST-L0-02",
"summary": "A write, a PUT or a DELETE, sent no X-Acting-Identity header, and no grant fixes the identity.",
"remedy": "Send the write again with an X-Acting-Identity header that gives the acting identity."
},
{
"name": "image_build_failed",
"surfaces": [
"management_action"
],
"status": 422,
"owner": "PLD-L0-90",
"summary": "deploy: the image or function build of the artifact ended failed, or ran past its fifteen-minute bound, so nothing was applied and the serving version is untouched. The history row ends failed with this outcome and a `build` member: the build steps' own last lines, scrubbed of addresses, header values, and tokens.",
"remedy": "Read the failed row's outcome through read_status or list_versions: its build member's output_tail shows the failing step, most often the dependency install. Fix the artifact, such as its package.json or its lockfile, and deploy again. Where the detail says the build failed pulling the platform's base image, deploy the same zip again."
},
{
"name": "image_expired",
"surfaces": [
"management_action",
"storage"
],
"status": 410,
"owner": "ACB-L0-93",
"summary": "The picture you requested, saved without an application, reached kept_until, the end of its 7-day keep. It is no longer served, even if the daily purge has not removed its row yet.",
"remedy": "Call generate_image for a new picture. Renewing a link does not extend the old picture's keep. Save a picture locally before kept_until, or generate into an application's storage to keep it there until deleted."
},
{
"name": "image_generation_busy",
"surfaces": [
"management_action"
],
"status": 429,
"owner": "ACB-L0-93",
"summary": "This replica is already holding as many image calls as the platform allows at once. Nothing was sent to the provider, and nothing was counted or saved.",
"remedy": "Repeat the request after a few seconds."
},
{
"name": "image_generation_failed",
"surfaces": [
"management_action"
],
"status": 502,
"owner": "ACB-L0-93",
"summary": "No image came back or none could be saved. The provider failed or dropped the connection, the hold expired, the answer held no picture, or the store refused the file. The call's place is given back and no charge is posted. If the give-back fails, it stays counted and uncharged, as the detail says. The body gives `used`, `free_images`, `resets_at`, and `saved`, which is false.",
"remedy": "Repeat the request. A repeat that delivers an image is free within the month's free images and charged past them. While the account is paused, a repeat past its free images meets account_paused. Where this keeps happening, quote the reference with submit_feedback.",
"members": {
"used": {
"type": "integer",
"description": "The account's images counted this UTC month: delivered images and calls whose give-back failed."
},
"cap": {
"type": "integer",
"description": "The account's images per UTC month, returned where pricing reads `plans`."
},
"resets_at": {
"type": "string",
"description": "The first instant of the next UTC month, as an ISO 8601 instant."
},
"saved": {
"type": "boolean",
"description": "False: no image was saved."
},
"free_images": {
"type": "integer",
"description": "The account's free images per UTC month, returned where pricing reads `usage`."
}
}
},
{
"name": "image_generation_limited",
"surfaces": [
"management_action"
],
"status": 429,
"owner": "ACB-L0-93",
"summary": "This account has reached its limit on image calls that reached the provider in the last hour and delivered no image. This request was not sent to the provider, counted, charged or saved. The body gives `per_hour`, the limit, and `resets_at`, when to repeat.",
"remedy": "Wait for the instant `resets_at` gives, then repeat with a changed prompt if calls were blocked, or quote the reference with submit_feedback if they keep failing.",
"members": {
"per_hour": {
"type": "integer",
"description": "The setting's number of image calls that reached the provider and delivered no image in the trailing hour."
},
"resets_at": {
"type": "string",
"description": "The instant the oldest counted call leaves the trailing hour, as an ISO 8601 instant."
}
}
},
{
"name": "image_generation_unavailable",
"surfaces": [
"management_action"
],
"status": 503,
"owner": "ACB-L0-93",
"summary": "The platform cannot make images right now. No file was saved. Nothing was counted unless `detail` says the call stays counted.\n\nThe platform has no key for this call, its key could not be read, it has no current price for the model, its monthly limit was reached, or the provider refused before any picture. A provider refusal normally gives the image back; if that fails, the refusal's `detail` says it stays counted. A call left counted is charged nothing.",
"remedy": "Nothing you do corrects this, because only the platform's operator stores the key and sets the ceiling. Repeat the request later. A ceiling that was reached clears at the first instant of the next UTC month."
},
{
"name": "image_link_spent",
"surfaces": [
"storage"
],
"status": 403,
"owner": "ACB-L0-93",
"summary": "The link is malformed, expired or replaced, or its hash matches no picture row. A link lasts at most one hour and never past the picture's kept_until. A new link ends the previous one.",
"remedy": "If the picture is still within its 7-day keep, call renew_image_link with the name generate_image returned and use the new link. You can also read its address under your own session credential or an account-wide token with no bounding grant. If the picture is gone, generate a new one."
},
{
"name": "image_not_found",
"surfaces": [
"management_action",
"storage"
],
"status": 404,
"owner": "ACB-L0-93",
"summary": "Your account holds no picture by this name, the picture was removed, or a link is for a different picture. This refusal concerns pictures generate_image saves without an application.",
"remedy": "Use the name generate_image returned for your picture saved without an application. If its 7-day keep has ended or the picture is gone, call generate_image for a new one."
},
{
"name": "incident_not_found",
"surfaces": [
"management_action"
],
"status": 404,
"owner": "PLD-L0-77",
"summary": "A staff write to the platform's incident record gave an incident that is not in it. Nothing is written.",
"remedy": "Read the open incidents and the history from the platform's status, then repeat the request with an id from that answer, or omit the incident member to open a new row."
},
{
"name": "ingest_failed",
"surfaces": [
"logging"
],
"status": 500,
"owner": "PLD-L0-80",
"summary": "The logging surface failed unexpectedly while taking the batch. The platform records the failure under a reference that the detail gives, and the detail never includes the error's own message.",
"remedy": "Nothing you do corrects this: the platform runs the logging store, and the client's later flushes deliver once it accepts batches again. Read the client's fallback output and the counter logging.dropped for the records the refused batch lost."
},
{
"name": "insufficient_scope",
"surfaces": [
"management_action",
"mcp_server",
"storage",
"egress",
"realm_surface",
"documentation",
"logging",
"push",
"email",
"deploy_progress",
"account_mail"
],
"status": 403,
"owner": "MCP-02",
"summary": "The OAuth access credential is valid for this service but lacks the scope required by the protected call; the challenge states the required scope.",
"remedy": "Start the OAuth authorization again from your tool and request the scope the challenge gives. Renewing the existing token does not add a scope."
},
{
"name": "internal",
"surfaces": [
"management_action",
"egress",
"builder_sign_in",
"realm_surface",
"push",
"email",
"deploy_progress",
"workflow_start",
"support_read",
"account_mail",
"payment_event"
],
"status": 500,
"owner": "PLD-L0-80",
"summary": "An unexpected error while responding. Where the detail gives a reference, the error is recorded on the platform side under that reference. The detail is a fixed sentence and never the error's own message.",
"remedy": "Retry the request. If the refusal repeats, report it and quote the reference its detail gives."
},
{
"name": "interrupted",
"surfaces": [
"management_action"
],
"status": null,
"owner": "API-L0-07",
"summary": "The recovery sweep marked this pending action failed after it stayed in the executing state for more than thirty minutes; read it through read_approval_status. The sweep runs once as the control plane starts, before it serves requests, and then every ten minutes. An interruption does not prove that nothing changed, so inspect the current state before you request and approve another attempt. A version-history row also ends failed with this outcome when the control plane process running its deploy, promote, or restart ended before it finished; read_status and list_versions show it (PLD-L0-63).",
"remedy": "Inspect the subject's current state before requesting another attempt. Where the act is still wanted, request it again and approve the new pending action in the browser. For a version-history row, run the deploy, promote, or restart again."
},
{
"name": "invalid_batch",
"surfaces": [
"logging"
],
"status": 400,
"owner": "LGS-01",
"summary": "The batch is not in the shape the logging surface reads. The body is not JSON, or not a JSON object with the members environment, entries, and counters, or entries or counters is not an array. Or an entry gives its own application or environment member, or the source header gives a value other than harness.",
"remedy": "Send the batch as one JSON object with the members environment, entries, and counters, in the shape the package's client forms. Give no entry an application or environment member, and send the source header only as harness. The detail says which check failed."
},
{
"name": "invalid_client",
"surfaces": [
"builder_sign_in",
"realm_surface"
],
"status": null,
"owner": "ACS-L0-15",
"summary": "On the realm surface, the client_id is missing or is not a native client the end-user realm declares (400, ACS-L0-15). This applies at the realm's authorization, token, and revocation endpoints and to a device registration. On the builder sign-in, the token endpoint and the device authorization endpoint refuse with 401 a client_id that no registration has; the revocation endpoint refuses it with 400 before reading the token. The authorize route shows the browser a page saying to connect your tool again (400, MCP-02).",
"remedy": "On the realm surface, declare the client on this environment's realm with its client_id and its redirect URIs. Use configure_app_sign_in where the manifest lists no clients for that environment; otherwise add it to the manifest's realm clients list for that environment, then call submit_manifest. Send the request with that client_id; read_app_sign_in shows the declared clients. On the builder sign-in, remove this server's sign-in in your tool and connect again, so the tool registers itself again. A script that signs in by the device-code grant registers its client again, then starts the sign-in again."
},
{
"name": "invalid_client_metadata",
"surfaces": [
"builder_sign_in"
],
"status": 400,
"owner": "MCP-02",
"summary": "Your dynamic client registration was refused. Its redirect_uris is not a list, lists more than ten URIs, or contains a URI that cannot be used, or it gives no redirect URI while `grant_types` is not the device-code grant alone. Or its token_endpoint_auth_method is not none.",
"remedy": "Register again with one to ten redirect URIs. Each is an absolute HTTPS URL, or an HTTP loopback URL at any port, with no user name, password, fragment, or wildcard in it, and none on a host this service serves. Send token_endpoint_auth_method as none, or leave it out. A script that signs in by the device-code grant alone may instead send `grant_types` containing only `urn:ietf:params:oauth:grant-type:device_code`, and no redirect URI."
},
{
"name": "invalid_cursor",
"surfaces": [
"management_action",
"storage"
],
"status": 400,
"owner": "OST-L0-02",
"summary": "The listing's cursor is not one the storage surface reads for this listing. It is malformed or not one string, it belongs to another listing, its name lies outside the prefix or breaks the rules for reaching a stored name, or it predates the opaque cursor. `list_storage_files` applies the same cursor check.",
"remedy": "List again from the first page, with no cursor, and pass back the cursor each page returns."
},
{
"name": "invalid_grant",
"surfaces": [
"builder_sign_in",
"realm_surface"
],
"status": 400,
"owner": "MCP-02",
"summary": "The token endpoint refused a code or a refresh token. It is unknown, expired, unbound, or mismatched, its sign-in has since ended, or its account no longer exists. A refresh token replayed outside its grace period is refused too, and an authentic replay still ends its token family when the token it replaced has expired. An unknown or already used device code is refused the same way. A passkey offer, or a registration from the offer or the passkey page, is refused with this name when a sign-out ended its sign-in during its window. The offer's ticket is then spent and no passkey is written. On an end-user realm, the token endpoint refuses a native client with this name. It refuses a code that is spent, expired, or unknown, was issued to another client, or was issued for another redirect URI. It also refuses a verifier that fails the challenge, and a refresh token that is neither the current nor the previous one of a live session. It refuses an ID token that the token exchange already accepted, presented again within its life. At an exchange, it also refuses a code whose account has since lost, by the operator's revocation, the access the sign-in was for. The response gives no product, and a new invitation is the way back.",
"remedy": "Start the sign-in again from your tool, so that a new authorization code and refresh token are issued. Do not send the refused code or refresh token again. Where a sign-out ended a passkey offer, sign in again and add the passkey from the site's passkey page. In a native app, start the sign-in again from the app, and do not present the refused code, refresh token, or ID token again. Where the account's access was turned off, a new invitation is the way back."
},
{
"name": "invalid_redirect_uri",
"surfaces": [
"management_action",
"realm_surface"
],
"status": 400,
"owner": "ACS-L0-15",
"summary": "A redirect URI is outside the three accepted forms: a reverse-domain custom scheme, https on one of the application's own hostnames, or loopback http. At the authorization endpoint, the URI is not one declared for the client the request gives, or it is an https URI on the application's custom domain outside the identifier's span. A presented URI must match a declared one exactly, character for character, except for a loopback URI's port.",
"remedy": "Declare the URI in one of the three forms, with no user information and no fragment. Declare it with configure_app_sign_in where the manifest lists no clients for that environment, or in the manifest's realm clients list for that environment, then call submit_manifest. Send the authorization request with that URI; a loopback URI may use any port."
},
{
"name": "invalid_request",
"surfaces": [
"management_action",
"storage",
"builder_sign_in",
"realm_surface",
"router",
"push",
"email",
"deploy_progress",
"mcp_server",
"egress",
"workflow_start",
"support_read",
"account_mail",
"payment_event"
],
"status": 400,
"owner": null,
"summary": "The input is malformed or missing, and the detail gives the member. Or the input has a NUL (U+0000) or an unpaired UTF-16 surrogate, and the detail gives the character. This is the generic validation refusal of every surface. On a management action, it also refuses a call that gives a member the action does not declare. The detail lists that member, a nested one by its path, and every member declared at that place. Where that list would pass the detail's budget, the detail gives each place's member count instead and points to the action's reference page, which lists them. It also refuses a body the surface could not read, or a path segment whose escape does not decode, in the surface's own form, repeating nothing from the request (PLD-L0-95). On `create_space`, it also refuses a `space` deleted within the last 35 days, while its deletion marker remains (ITS-L0-06), and nothing is created. At a request for the `tzmesh` resource, and at the completion of its sign-in, it also refuses a browser's prefetch, which holds no confirmation. On `deploy_files`, a list entry with `content` under a path segment the zip leaves out is refused with `kept` and `refused`. Its `kept` lists the content entries kept and each entry by `sha256` alone whose file the platform holds and could read as the refusal was built; `refused` lists the entries refused.\n\nOver HTTP, a value outside a bound an action's reference states is refused `invalid_request`. Over MCP, your client's or the SDK's argument check runs first. A rule checked only by the handler draws `invalid_request` on either route. On the payment event route, a missing, malformed, invalid or stale signature, an unreadable event, or an event in the other mode receives the same refusal and changes nothing. The detail discloses no class or request content.",
"remedy": "Correct the member the detail gives, or send a member the action declares in place of one it does not; the detail or the action's reference page lists them. Or remove the character the detail identifies. Then send the request again. For a deleted space's identifier, pass another `space`, or leave it out and the platform chooses one. A refused prefetch needs nothing: the request is served when the person opens it.",
"members": {
"kept": {
"type": "array",
"description": "On a `deploy_files` list whose content entries are refused one by one, each content entry kept and each entry by `sha256` alone whose file the platform holds and could read as the refusal was built, in the list's order. Files that passed, and those earlier calls kept, are held now, and a retry gives each by its `sha256`.",
"items": {
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "The entry's path, as the list gave it."
},
"sha256": {
"type": "string",
"description": "The SHA-256 the platform computed over the content it received, the hash a retry gives."
}
}
}
},
"refused": {
"type": "array",
"description": "On a `deploy_files` list whose content entries are refused one by one, each refused entry, in the list's order. The list is never empty, and its first entry is the one the detail cites.",
"items": {
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "The entry's path, as the list gave it."
},
"error": {
"type": "string",
"description": "The refusal name the entry met."
},
"received_sha256": {
"type": "string",
"description": "With `deploy_files_hash_mismatch`: the SHA-256 the platform computed over the content it received, which the hash the call gave did not match."
}
}
}
}
}
},
{
"name": "invalid_scope",
"surfaces": [
"builder_sign_in"
],
"status": 400,
"owner": "MCP-02",
"summary": "The OAuth scope you requested is unknown, malformed, or broader than the recorded grant.",
"remedy": "Request only scopes the authorization-server metadata publishes, or leave out the scope parameter to get the default. To widen a grant, start a new authorization from your tool instead of refreshing."
},
{
"name": "invalid_target",
"surfaces": [
"builder_sign_in"
],
"status": 400,
"owner": "MCP-02",
"summary": "The OAuth resource you sent differs from this service's configured resource, or from the resource recorded at authorization.",
"remedy": "Send the resource parameter exactly as the protected-resource metadata gives it, or leave it out so that the configured service is selected and the recorded resource kept."
},
{
"name": "invalid_token",
"surfaces": [
"management_action",
"mcp_server",
"storage",
"egress",
"realm_surface",
"logging",
"push",
"email",
"deploy_progress",
"account_mail"
],
"status": 401,
"owner": "MCP-02",
"summary": "A protected call presents a credential that cannot authenticate to this service, and the WWW-Authenticate header gives the standard OAuth error. A missing credential gets no OAuth error parameter.",
"remedy": "Renew the access token with your refresh token where your tool has one; otherwise sign in again through your tool. An application's backend presents its current platform credential, or a minted token bounded to the application."
},
{
"name": "invited_realm_refuses_work_account",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "ACS-L0-09",
"summary": "On configure_app_sign_in: an invitation-only realm lists the work-account route. A realm is invitation-only by its configured creation mode or by the manifest's invited audience.",
"remedy": "Call configure_app_sign_in again with entra left out of sign_in_methods, or with creation set to open so the realm accepts users by their membership of the tenant rather than by invitation. Under the manifest's invited audience creation stays invitation-only, so leave the route out there.",
"members": {
"creation": {
"type": "string",
"description": "The creation mode the realm would enforce after the call, invited at this refusal."
},
"audience": {
"type": "string",
"description": "The audience the application's recorded manifest declares: public, invited, or workforce."
}
}
},
{
"name": "issue_refused",
"surfaces": [
"management_action"
],
"status": null,
"owner": "MAPI-18",
"summary": "The issue service refused the act you relayed with relay_issue_act: for its content, the issue's state, a lease, or a record the act refers to that does not exist. The status is the service's own, and the `refusal` member gives the service's refusal.",
"remedy": "Read the `refusal` member against the Issue Tracking contract's refusals. Correct the act's body, or the state of the issue it points to, and relay the act again.",
"members": {
"refusal": {
"type": "string",
"description": "The issue service's own refusal name, one the Issue Tracking contract states."
}
}
},
{
"name": "issue_service_unreachable",
"surfaces": [
"management_action"
],
"status": 503,
"owner": "MAPI-18",
"summary": "The issue service did not respond to a call the platform made for this action. The transport failed, the call passed its time bound, the service returned a fault of its own or the router's quota refusal, or it refused the platform's own credential. The detail gives the cause word in parentheses.",
"remedy": "Repeat the request after a short wait with the same key, which the service reads as a retry. If the refusal continues, report it with its reference through another route."
},
{
"name": "issue_tracking_application_required",
"surfaces": [
"egress"
],
"status": 403,
"owner": "EGW-L0-08",
"summary": "The platform upstream issue-tracking accepts only an application's platform credential or a minted token bounded to one application, because the space belongs to one application. An account-wide session or token is refused with this name.",
"remedy": "Make the call under the application's own platform credential, or under a token that mint_token bounds to that one application. To read an application's reports yourself, call read_feedback with the application's space. Settle its issues with settle_feedback and the space, or through relay_issue_act under an issues token."
},
{
"name": "issue_tracking_call_refused",
"surfaces": [
"egress"
],
"status": 403,
"owner": "EGW-L0-06",
"summary": "The platform upstream issue-tracking accepts only the calls that the issue tracking package's permission-level table marks as allowed through the gateway. For an application using its own space or a space of its account, it accepts only the calls of the level it reaches that space at. The `report` level, the level of an application's own space in both environments, can file and read reports, and cannot update or settle anything. Every other call path is refused with this name before any token is read. Among them are delete_space, the stored-bytes read, and every 0.3.0 call except submit, read, list, and search. At the `report` level, a list call that filters by proposed is refused before any token is read, on either wire, while its other filters are accepted. A binding with a `components` list can make only the 0.3.0 submit, read, list, and search calls. Every other call is refused for it, the whole 0.2.0 wire included.",
"remedy": "Make only the calls the issue tracking package's client makes on the gateway, within the level your application reaches its space at. You update, settle, and export the space through the management actions under an issues token. The platform deletes a space with its application, and no call of the application deletes it. At the `report` level, leave proposed out of a list call: its other filters are accepted, and a binding at the contribute level can filter by it. Under a binding with a `components` list, make only those four calls, on the 0.3.0 wire."
},
{
"name": "issue_tracking_not_provisioned",
"surfaces": [
"egress"
],
"status": 409,
"owner": "EGW-L0-06",
"summary": "The platform upstream issue-tracking found no issue-tracking space for your application's calling environment: no space is bound to it, and no space token is stored for it. The detail gives the manifest kind issue_tracking, whose declaration provisions a space.",
"remedy": "Add {\"kind\": \"issue_tracking\"} to the manifest's services and submit it with submit_manifest, which provisions one space for both environments. Where that provisioning was refused, or the application has a space for each environment, production's space is provisioned at the first promote, or at a one-environment application's first production deploy. Then repeat the request."
},
{
"name": "issue_tracking_unavailable",
"surfaces": [
"egress"
],
"status": 503,
"owner": "EGW-L0-06",
"summary": "The platform upstream issue-tracking cannot pass the call on. Either this platform serves no issue service, so its gateways have no service origin, or the environment's space token is stored but its value could not be read. The detail says which, and the call reaches no service.",
"remedy": "Repeat the request after a short wait, because a failed read of the stored token may succeed on the next call. Where the detail says no issue service is served, nothing you do corrects it, so report it with its reference."
},
{
"name": "issuer_mismatch",
"surfaces": [
"realm_surface"
],
"status": 403,
"owner": "ACS-L0-09",
"summary": "The work-account or Sign in with Apple id_token gives an issuer other than the pinned one.",
"remedy": "On the work-account route, confirm with read_app_sign_in that entra.tenant is the Directory (tenant) ID of the app registration, correcting it with configure_app_sign_in where it differs, then ask the end user to sign in again. If the refusal repeats, ask the client's tenant administrator to check the registration that issues the token. On the Sign in with Apple route, nothing in the realm's settings corrects this: ask the end user to sign in again."
},
{
"name": "issues_bounded",
"surfaces": [
"management_action"
],
"status": 403,
"owner": "MAPI-16",
"summary": "You reached an action outside the bound with a minted token that has the issues grant and no super_admin. The grant limits its token to list_tokens and relay_issue_act, whose `admits` marks list it. The rows marked access: anonymous are outside the bound and serve the token as they serve every connection.",
"remedy": "Call the action from the owner's signed-in session, or under a token minted through mint_token without the issues grant. The refusal's `admitted` member lists the actions the bounded token can reach.",
"members": {
"grant": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]*$",
"description": "The grant that bounds the credential presented."
},
"admitted": {
"type": "array",
"items": {
"type": "string"
},
"description": "The actions the bound admits, in the enumeration's order: the rows the grant marks and the rows whose admits mark lists it. The rows marked access: anonymous lie outside the bound and are not listed."
}
}
},
{
"name": "issues_level_refused",
"surfaces": [
"management_action"
],
"status": 403,
"owner": "MAPI-16",
"summary": "The level of your token's issues grant does not allow the act. On relay_issue_act, report files, follows, checks, and reads; contribute also works issues; owner reaches every act the relay passes on. Below the owner level, an update whose fields set restricted to any value but true is refused too, because only the owner level lowers the mark. Below the owner level, an update whose fields give alarm, with any value, is refused too, because only the owner level clears an alarm. At the report level, a list that gives proposed, with any value, is refused too, because that selection reads proposals the level does not read. On mint_token, an account that is a member of a space is refused a level above the one the space's owner gave it.",
"remedy": "Pass an act the `admitted` member lists, or mint a token at a level that allows the act from a signed-in session of the account. At the report level, leave proposed out of a list. On mint_token, mint at the level the space's owner gave you or below, or ask the owner for a higher level.",
"members": {
"level": {
"type": "string",
"description": "The level of the token's issues grant."
},
"admitted": {
"type": "array",
"items": {
"type": "string"
},
"description": "The acts the level admits, in the relay's order."
}
}
},
{
"name": "key_revoked",
"surfaces": [
"realm_surface"
],
"status": 401,
"owner": "ACS-L0-08",
"summary": "On the session re-issue route, the realm key that signed the presented session token was revoked with revoke_app_sign_in_keys. The session ends, and the end user signs in again.",
"remedy": "Have the end user sign in again from the application. Repeating the re-issue request never restores a session whose token a revoked key signed."
},
{
"name": "level_invalid",
"surfaces": [
"management_action"
],
"status": 400,
"owner": "MAN-03",
"summary": "On submit_manifest: the issue_tracking entry gave a `space` and a `level` other than `report` or `contribute`. That is `owner`, which no deployment can have, or a word that is not a level. Or it gave `components` with a `level` other than `report`, or bound the platform's own space at a level other than `report`. Nothing was recorded.",
"remedy": "Pass `report` or `contribute`, or leave `level` out for `report`. With `components`, and for the platform's own space, pass `report` or leave `level` out. Your wider reach to a space, such as settling and exporting, comes from an issues token minted with mint_token, never from a deployment."
},
{
"name": "library_entry_not_served",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "MAPI-26",
"summary": "A `deploy_files` list left out a library copy that the root package.json declares at a `file:` path. The recorded manifest's `packages` row for it gives a version or an entry the library does not serve, so the platform cannot fill the copy. The detail gives the row, the copy's path, and, where the library serves the entry, its served version. Nothing was started.",
"remedy": "List the project's own copy of the entry in `files`. If the person chooses the version the library serves, either take it with library take or set the manifest's `packages` row to that version without taking a local copy; then call submit_manifest with the updated manifest and send the file list again. Keep the root `package.json` declaration of the entry's `file:` dependency so the platform can fill the copy. The version-change routes are available only where the library serves that entry."
},
{
"name": "local_route_required",
"surfaces": [
"management_action",
"mcp_server"
],
"status": 409,
"owner": "SEC-L0-07",
"summary": "You called store_secret with replace: true on the development scope with the platform-minted name of the platform credential or the database credential, on a surface other than the HTTP wire route. Such surfaces include the MCP tool, the dashboard, and a browser session. They return no platform-minted credential value, so the re-mint was refused before any write (SEC-L0-07). The same call on the wire route re-mints and returns the value once. The line returned to the submit_manifest call that turnzero provision prints makes that call and writes the environment file. A call with no value returns the command that sends the value from your machine. A `deploy` call on the MCP surface carrying `zip_sha256` is refused too, and nothing is prepared: the turnzero command sends it only on the HTTP action route (PLD-L0-86; MAPI-08). A mint_token call on the MCP surface with `code_verifier` is refused too, with nothing minted: the turnzero command presents it only on the HTTP action route (MAPI-23; MAPI-08). A sign_in_test_end_user call on the MCP surface with `delivery` is refused too, and nothing is signed in. The turnzero command sends it only on the HTTP action route, and a tool takes the line the call returns without it (ACS-L0-21; MAPI-08).",
"remedy": "Run `turnzero provision --application <application id>` with nothing piped, adding `--origin` where your other lines include one, and make any call it prints. Its line makes the same store_secret with replace: true call on the HTTP wire and writes the new value into your environment file. To rotate a value of your own, call store_secret with replace: true from your tool with no value. Then run the command the answer returns, or command_windows on Windows: it reads the value on your machine and sends it on the HTTP wire. For `deploy`, call `deploy_command` giving the application, and run the command it returns, or `command_windows` on Windows. For sign_in_test_end_user, omit delivery from the tool call and run the returned turnzero session line. The command sends delivery on the HTTP route and writes the cookie jar without returning the session value to your AI coding tool.",
"members": {
"application": {
"type": "string",
"description": "The id of the application whose platform-minted development credential the call asked to re-mint."
}
}
},
{
"name": "log_capacity_reached",
"surfaces": [
"logging"
],
"status": 409,
"owner": "LGS-L0-13",
"summary": "The batch's app or harness entries would take that source's retained log bytes in the application environment past the application's retained-bytes bound. It is the size's log-retained-capacity quantity, or the larger fixed bound with the 30-day log option. The whole batch is refused, and the refusal is counted in the stream's counter logging.refused_capacity. Entries leave the store when their retention period ends, and purge_logs erases the stream now.",
"remedy": "Erase the environment's stream with purge_logs, or wait for entries to expire. Entries are kept for 7 days without the option and 30 days with it. To raise the retained-bytes bound, turn on the charged option with set_log_retention only at the account owner's request. If their choice is missing and nobody can answer, report the refusal and leave the option unchanged. The client does not resend the refused batch and writes it to its fallback output instead."
},
{
"name": "manifest_invalid",
"surfaces": [
"management_action"
],
"status": 400,
"owner": "MAN-12",
"summary": "On submit_manifest: the manifest fails the manifest contract. The violations give the failing paths, and a schema violation's detail gives the manifest_schema:<member> read of each schema member they fall in, at most three. A setting name the reserved-name rule refuses is one such path (MAN-14). So is an `upstreams` entry a rule of declare_outbound_api refuses, the violation giving that rule's error (EGW-L0-02). So is a listed storage area the minting route's rule refuses, its violation giving that rule's error (OST-L0-01). On deploy or promote: a setting the recorded manifest binds has a name the reserved-name rule now refuses, and the detail gives it.",
"remedy": "Correct the manifest at each JSON path the violations list, or at the setting the detail gives, then call submit_manifest again.",
"members": {
"violations": {
"type": "array",
"items": {
"type": "string"
},
"description": "One entry per violation, each the JSON path of the failing member, a colon, and the message. The root of the document is written as a single slash."
}
}
},
{
"name": "manifest_missing",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "PLD-L0-63",
"summary": "On deploy: no manifest is on file for the application. Call submit_manifest first.",
"remedy": "Call submit_manifest for the application, then deploy again."
},
{
"name": "manifest_owned_field",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "EGW-L0-02",
"summary": "On declare_outbound_api, configure_app_sign_in, or configure_push: the call would change something the application's recorded manifest sets. That is an upstream listed in its `upstreams` member, a field set in its `realm` member, or a provider listed in its push entry. The detail lists each field. On declare_outbound_api with remove true, the recorded manifest's `upstreams` member lists the upstream, so it cannot be ended: neither a submission nor a call ends an upstream the member lists. Nothing was written.",
"remedy": "Change the member in the manifest and call submit_manifest, which records it. Or remove it from the manifest and submit the manifest; the action can then change it. To end an upstream, remove the entry and submit the manifest, deploy and promote the version that no longer calls the upstream, then call declare_outbound_api with remove true again."
},
{
"name": "method_not_allowed",
"surfaces": [
"management_action",
"storage",
"router"
],
"status": 405,
"owner": "MAPI-10",
"summary": "A mutating action was reached with GET, or a storage route with a method it does not serve. Or the serving domain's apex or its www name was reached with anything but GET or HEAD of /.",
"remedy": "Send a mutating action with POST. On a storage route, repeat the request with the method the detail gives: PUT declares an area, and a file accepts PUT, GET, or DELETE. On the serving domain's apex or its www name, send the request to the application's own hostname."
},
{
"name": "migration_busy",
"surfaces": [
"management_action"
],
"status": null,
"owner": "DBS-L0-06",
"summary": "A serverless deploy, promote or rollback would exceed a limit on migration runs in its management service process or owning account. Read migration_busy and detail in the failed version row through read_status or list_versions; this is not the initiating call's answer. This run opened no migration session and applied no file. An earlier version keeps serving; otherwise nothing serves.",
"remedy": "After a moment, repeat the failed deploy, promote or rollback. This refusal queues no migration run; the repeated act tries admission again. Leave recorded migration files unchanged."
},
{
"name": "migration_edited",
"surfaces": [
"management_action"
],
"status": null,
"owner": "DBS-L0-06",
"summary": "A serverless deploy, promote or rollback found a migration file whose text differs from the hash recorded by the database. Read migration_edited and detail in the failed version row through read_status or list_versions. This is not the initiating call's answer. This migration walk committed no file. The earlier version keeps serving. Where none was serving, nothing serves afterwards.",
"remedy": "Restore the recorded file and add a new migration file for the change. If only development recorded the file, clear_development_database can clear that database after browser approval. Deploy again afterwards. This walk rolls back its edited-file check before any file runs, so it commits no migration. Files committed by earlier runs remain applied."
},
{
"name": "migration_failed",
"surfaces": [
"management_action"
],
"status": null,
"owner": "DBS-L0-06",
"summary": "A serverless deploy, promote or rollback failed at migrations. Read migration_failed and detail in the failed version row through read_status or list_versions. This is not the initiating call's answer. Detail gives the file and SQLSTATE when available. SQLSTATE 57014 means cancellation; a file can change the initial thirty-second statement limit. Other causes include a connection failure or ten-second opening timeout, an oversized file answer, or the five-minute run limit. The session can also exceed 32 MiB received or a walk statement's 65,535-row limit. The earlier version keeps serving; where none was serving, nothing serves. Committed files stay applied. This error also covers an environment with no database.",
"remedy": "Read detail and query_database. For connection failures or run limits, repeat the failed deploy, promote or rollback; only absent files run. For 57014, shorten the statement or retry after the lock is free. For an answer or receive limit, remove large queries. Split a file that cannot finish alone within five minutes. Change only unrecorded files; otherwise add a new file. If only development recorded it, clear_development_database can clear it after browser approval, deleting development data and migration records. Wait for completion before editing. Deploy changed files; with development on, deploy there, then promote. For a ledger over 65,535 rows, report with submit_feedback; never delete migration records to retry. With no database, declare it or omit migrations, then deploy. Rollback undoes no migration."
},
{
"name": "migrations_too_large",
"surfaces": [
"management_action"
],
"status": 400,
"owner": "DBS-L0-06",
"summary": "A serverless deploy or its check found too many declared bytes in the zip's migration records. Each direct .sql record under the root migrations/ folder counts by its larger compressed or uncompressed size. Other files do not count toward this bound; the whole-zip bound still applies. The start checks refuse before any version row or write. This is the initiating call's answer.",
"remedy": "Keep the migration records within the size limit and deploy again. Migration files hold schema changes; put seed data elsewhere. Do not edit a migration already recorded by the database: put later changes in a new file."
},
{
"name": "migrations_without_database",
"surfaces": [
"management_action"
],
"status": 400,
"owner": "PLD-L0-63",
"summary": "The start checks for a serverless deploy, or deploy_files with check_only, found .sql migration files without a database declared in the recorded manifest. The files are directly under the zip's root migrations folder. Nothing was written. check_deploy reads no zip.",
"remedy": "Declare the database in the manifest and submit it, or leave the migrations folder out. Check and deploy again."
},
{
"name": "misdirected_origin",
"surfaces": [
"builder_sign_in",
"egress",
"logging",
"management_action",
"mcp_server",
"realm_surface",
"storage",
"documentation",
"push",
"email",
"account_mail"
],
"status": 421,
"owner": "PLD-L0-67",
"summary": "Your request reached a public service without going through the platform's edge. Behind the edge, every request must include the edge's profile identifier in its identifier header, and a forwarded host and scheme equal to the configured origin (PLD-L0-67). A request that does not is refused before any route runs. The detail gives the forwarded host and scheme the service saw. A request from an address of a hosting cell is refused the same way even when it has the identifier, and its detail gives that address. The health reads, and the sign-in requests the platform's serving router forwards for an application's end-user realm, are exempt. The check is off where no edge profile identifier is configured. Where an estate sets a REST host, that host serves its own API path and nothing else, and that path is refused under any other host, the public origin among them; this holds with or without an edge profile identifier.",
"remedy": "Send the request through the platform's edge to the public origin the detail gives, https://turnzero.ai on production, and not to a service's own hostname. The detail also gives the host and scheme the service saw. Where the detail gives a REST host's address, call that address."
},
{
"name": "move_refused",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "ACB-L0-106",
"summary": "The application move or its later file removal is blocked. detail lists the blocking cases and counts any that did not fit. Nothing changed, and a refused move request creates no pending action.",
"remedy": "Resolve the listed cases, then repeat this action. For settings_not_recorded, deploy first. For before_stale_ceiling, wait until the instant given. For no_completed_move, read read_approval_status through the Turn Zero Cloud connection as the requesting account. Removal needs a completed or failed record with moved: true and files. Do not start another move merely to obtain that record. Settle an area-name conflict before retrying removal."
},
{
"name": "name_bound_to_push",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "PSH-L0-01",
"summary": "On declare_outbound_api or configure_app_sign_in: the credential name is a push provider credential of this application's push configuration, which serves no upstream and no realm route. On submit_manifest, deploy, or promote: a `settings` entry binds such a name, and a push provider's credential is never bound into a process (MAN-14). Nothing was recorded or written.",
"remedy": "Store the upstream's, the realm route's, or the bound setting's value under another name with store_secret, and declare, configure, or bind that name. A push provider's credential belongs to the push service alone. For a binding, call submit_manifest again, then deploy or promote."
},
{
"name": "name_bound_to_realm",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "ACS-L0-09",
"summary": "On declare_outbound_api or configure_push: the credential name is in the cell's realm vault, or is a realm's configured work-account client secret or Apple signing key, which serves no upstream and no push provider. On submit_manifest, deploy, or promote: a `settings` entry binds such a name, and a realm's route credential is never bound into a process (MAN-14). Nothing was recorded or written.",
"remedy": "Store the upstream's, the push provider's, or the bound setting's value under another name with store_secret, and declare, configure, or bind that name. A realm's client secret or signing key belongs to the realm alone. For a binding, call submit_manifest again, then deploy or promote."
},
{
"name": "name_bound_to_setting",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "MAN-14",
"summary": "On configure_app_sign_in or configure_push: a setting binds the secret the call gives, in the application's recorded manifest, in either environment's serving row, or in a deploy, promote, or restart in flight to either. A realm's route credential or a push provider's credential is never bound into a process. The detail gives the setting and where it is bound. On those actions, a refusal before the write writes nothing. A refusal after the write takes the call's credentials back, and any whose read then fails stays as recorded. On submit_manifest and create_environment, a binding can be recorded after the check and feed a credential that the realm member or the push entry refers to. Each such credential is then taken back where the record changed it. A submission's manifest stays recorded, and its detail lists the realms, or the push configurations, done and those not.",
"remedy": "Store the secret under another name at the application's scope with store_secret, then call configure_app_sign_in or configure_push again with that name. A running copy keeps a binding until that environment's next deploy or promote of a manifest that no longer binds the name, and an act in flight keeps it until that act ends. On submit_manifest, store the secret under another name and change the member or the entry, or remove the binding, then submit the manifest again. On create_environment, do the same and submit the manifest, or remove the binding and call create_environment again."
},
{
"name": "name_bound_to_upstream",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "ACS-L0-09",
"summary": "configure_app_sign_in or configure_push: the secret you gave is the credential of an upstream declaration bound to this application. A realm's route credential or a push provider's credential cannot also serve an upstream.",
"remedy": "Store the secret under another name at the application's scope with store_secret, then call configure_app_sign_in or configure_push again with that name. The upstream keeps its own credential name."
},
{
"name": "name_taken",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "SVC-L0-07",
"summary": "create_application and rename_application: your account already has a live application by that name.",
"remedy": "Choose a readable name that no live application of your account uses, then repeat create_application or rename_application. A name is freed when the application that uses it is deleted or renamed."
},
{
"name": "never_deployed",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "PLD-L0-59",
"summary": "read_logs or read_counters: the environment you read has no deployed version. For a container read, the environment has no compute, no record from a failed first health check, and no in-flight version or upload that draws deploy_in_flight (PLD-L0-63). A read of local needs no deploy. The `request_route` and `write_route` actions are refused with it where the environment you give serves no version, so there is no route to call (MAPI-28).",
"remedy": "Put a version in that environment first, with deploy, or with promote for production on an application with two environments, then repeat the read, or the request_route or write_route call. Where it gives a version whose deploy or promote failed, read the failure in read_status's outcome for that version instead. Where it points to development's kept lines, repeat the read with environment development."
},
{
"name": "no_address",
"surfaces": [
"account_mail"
],
"status": 409,
"owner": "EML-L0-10",
"summary": "The account holds no verified address, so nothing was queued.",
"remedy": "Add a verified address to the account, then send again."
},
{
"name": "no_such_account",
"surfaces": [
"management_action"
],
"status": 404,
"owner": "ITS-L0-07",
"summary": "share_space: no account signs in with the address you gave, and nothing was written. A member must be an existing account, matched by the address of its emailed-code sign-in, and nothing is kept for a later sign-in.",
"remedy": "The address must belong to an existing account: ask its owner to create an account and sign in once with that address. Then repeat the request with the address they sign in with."
},
{
"name": "no_such_application",
"surfaces": [
"management_action",
"storage",
"logging",
"push",
"email",
"account_mail"
],
"status": 404,
"owner": null,
"summary": "The application is not in the acting account.",
"remedy": "Check the application id against list_applications and repeat the request with an id it returns. Where a platform credential rather than an id identified the application, the application was deleted, so stop the process that presents that credential. Under the turnzero command's computer token, the detail gives the account the call acted as. An id that belongs to another account is refused application_other_account instead."
},
{
"name": "no_such_end_user",
"surfaces": [
"management_action"
],
"status": 404,
"owner": "ACS-L0-08",
"summary": "No end user by that identifier in the realm of the application the request gives.",
"remedy": "Check the end user's id and the environment against list_end_users for that application, then repeat the request with an id it returns."
},
{
"name": "no_such_entry",
"surfaces": [
"management_action"
],
"status": 404,
"owner": "LC-01",
"summary": "read_library: the name you gave is not in the served library, or the file you gave is not a file of that entry.",
"remedy": "Call read_library to see the served entries, then repeat read_library with a name from that list. If you also passed file, repeat the read with the entry path the refusal gives, or read the entry without file first and take the path from its file list."
},
{
"name": "no_such_file",
"surfaces": [
"management_action",
"storage"
],
"status": 404,
"owner": "OST-L0-07",
"summary": "No file by that name exists in the area, or a put with If-Match gave a name that does not exist. Under an export's download grant, a stored file created after the export listed its files is refused the same way. `read_storage_file` also refuses a file name that is absent.",
"remedy": "Check the file name the detail gives against the area's file listing. To create a name that does not exist yet, send the put without If-Match, or with If-None-Match: *. Under an export's download grant, call `request_export` again and download the new export, which has the application's files as they are now."
},
{
"name": "no_such_schedule",
"surfaces": [
"management_action"
],
"status": 404,
"owner": "SCH-L0-06",
"summary": "The application declares no schedule of that name for that environment.",
"remedy": "Read the environment's declared schedules with read_schedules and repeat the request with one of the names it lists. A schedule not in that list must be declared before it can run."
},
{
"name": "no_such_version",
"surfaces": [
"management_action"
],
"status": 404,
"owner": "PLD-L0-43",
"summary": "promote or roll_back: the version you gave is not the number of a deployed version-history row of the application, or that row was retired when its environment was deleted. The `list_versions` action returns the rows a promote can take.",
"remedy": "Call list_versions to read the application's deployed version numbers, then repeat promote or roll_back with one of them."
},
{
"name": "nonce_mismatch",
"surfaces": [
"realm_surface"
],
"status": 403,
"owner": "ACS-L0-09",
"summary": "The work-account or Sign in with Apple id_token nonce is not the one this sign-in attempt issued.",
"remedy": "Ask the end user to start the sign-in again from the beginning, so that a new attempt issues its own nonce."
},
{
"name": "not_configured",
"surfaces": [
"router",
"workflow_start",
"payment_event"
],
"status": 503,
"owner": null,
"summary": "The platform-internal resolve endpoint has no router resolve secret configured, or the serving router's invoke endpoint has no invoke secret configured. On the start-line route, a plane whose setting gives no repository, or that has no status record to write to, refuses every line with this before reading the token (PLD-L0-76). On the payment event route, the estate's provider settings are absent, incomplete or in different modes, so the route accepts no event.",
"remedy": "Nothing you do corrects this. The platform's operator sets the missing secret or setting and restarts the services that read it."
},
{
"name": "not_deployed",
"surfaces": [
"router"
],
"status": 404,
"owner": "SVC-L0-07",
"summary": "The environment the hostname reaches has no deployed version yet, so nothing is served there, the shell included.",
"remedy": "Deploy a version, or on an application with two environments promote one to production, then request the hostname again. An end user asks the application's author to do so."
},
{
"name": "not_found",
"surfaces": [
"management_action",
"realm_surface",
"push",
"email",
"support_read",
"account_mail",
"dashboard_picture",
"router"
],
"status": 404,
"owner": null,
"summary": "You gave a pending action, secret, operated account, token, connection, realm action's invitation, synthetic purge, or export that does not exist or is not yours (ACS-L0-08 for the invitation; ACS-L0-11 for the connection). For clear_development_database, the application you gave has no development database (DBS-L0-10). For query_database, the environment you gave has no database (DBS-L0-11). For request_export with download: true, the export's files are no longer in its export area (API-L0-23). For the four feedback actions, the `space` you gave is no issue space your account has, refused before any token is read (ITS-L0-03). On the realm surface, the session a revocation from the session list gives is no live session of the signed-in end user (ACS-L0-17). On the device routes, the installation identifier matches no registration of the signed-in user. On the push surface, the request uses a path or a method under /push/v0 other than POST /push/v0/messages. On the realm surface, the request uses a path or a method under /__account/ that no realm route serves, the OpenID Connect discovery path among them (ACS-L0-04). For a staff read of a synthetic account's state, the `account` you gave is an id that belongs to no account, under `super_admin`.\n\nThe dashboard picture route is unconfigured, the dashboard session does not verify, or the account has no tzMesh profile, person or picture.\n\nOn the serving router, the serving serverless version has no file or function for the requested path and method. A pool response can also report that its loaded version has no function for the path. Nothing was run.",
"remedy": "Check the identifier against the listing for its kind: list_secrets, list_tokens, or list_invitations. For a pending action, a purge, an export, or a seeded or first-sign-in account, check it against the id an earlier response returned. Then repeat the request with an identifier that belongs to your account. For the feedback actions, pass a space that list_issue_spaces or submit_manifest's receipt returns, or leave `space` out for the platform's own space. On the realm surface, read the session list at GET /__account/sessions and pass an id it returns. For clear_development_database there is nothing to clear: a development database exists once a submitted manifest declares the database kind. For query_database there is nothing to read: an environment's database exists once a submitted manifest declares the database kind. For a path no realm route serves, read the realm's endpoints at /.well-known/oauth-authorization-server on the hostname, which is served where the realm declares a client.\n\nThe dashboard picture route takes no identifier. Sign in if needed; without a picture, use initials.\n\nFor a serverless route, check the path and method against the serving version's client files and functions. Deploy missing code or files, or use a path that version serves."
},
{
"name": "not_test_end_user",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "ACS-L0-21",
"summary": "A `read_test_signin_code` or `sign_in_test_end_user` call gave a user who is not an unexpired test end user of the request's realm, or a label that reaches none. An `add_test_end_users` call with `remove: true` gave a user who is not a test end user of that realm. Or a creation gave a label whose address another end user of the realm already has. The deletion refuses whole and removes nothing; the read returns nothing; the sign-in signs no one in; the creation creates nothing.",
"remedy": "Pass test end users of that realm, the rows list_end_users marks with test true. The read needs one whose expires_at has not passed, and add_test_end_users with labels makes an expired one afresh. Remove a real end user with delete_end_user."
},
{
"name": "not_yet_provisioned",
"surfaces": [
"management_action",
"mcp_server"
],
"status": 501,
"owner": "MAPI-10",
"summary": "An enumerated action this build or estate does not serve. Either no build serves the action, or it needs a service the estate does not run. The feedback actions, a recorded check, list_issue_spaces, create_space, share_space, list_space_members, delete_space, rename_space, and relay_issue_act need the issue service, as does submit_manifest declaring the issue_tracking kind.",
"remedy": "Read the action's page under the Management actions reference. Where no build serves the action, call one the platform serves instead; no retry succeeds. Where the estate runs no service the call needs, nothing you do corrects it until the estate serves that service."
},
{
"name": "nothing_to_promote",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "PLD-L0-43",
"summary": "promote: the request gives no version, and the development environment has no serving version, so nothing can be promoted. Deploy to development first.",
"remedy": "Deploy to the development environment, then call promote again. Or call promote with a deployed version number, which list_versions returns."
},
{
"name": "notice_not_published",
"surfaces": [
"management_action"
],
"status": 404,
"owner": "API-L0-12",
"summary": "The notice you requested has no file at `cloud/notices/<notice>.json` on the served site. Nothing was sent and no account was claimed.",
"remedy": "Check the notice's name, or publish its approved words and audience file with the site. Then call again."
},
{
"name": "notice_words_refused",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "API-L0-12",
"summary": "The notice's published file could not be read or failed its shape check; the detail gives the reason. Nothing was sent and no account was claimed.",
"remedy": "Correct the reason the detail gives and publish the file again. Get the developer's approval for any changed words or audience before sending."
},
{
"name": "offer_cookie_required",
"surfaces": [
"builder_sign_in"
],
"status": 400,
"owner": "ACS-L0-10",
"summary": "You reached a passkey offer route without the offer cookie the offer page set, or with another value. Signing out in that browser clears the cookie.",
"remedy": "Respond to the offer from the browser that showed the offer page, while the offer is still open. If that browser is closed, sign in again and respond to the new offer there, or add the passkey later from the site's passkey page."
},
{
"name": "option_not_set",
"surfaces": [
"management_action"
],
"status": 503,
"owner": "ACB-L0-26",
"summary": "The month's line for a monthly option was posted or already covered, but the option was not turned on. The line remains recorded.",
"remedy": "Retry the call if you still want the option. In the same UTC calendar month, no further line is posted while the month's charged count covers your options of this kind with this one included. For a log option, the application must still exist."
},
{
"name": "origin_not_admitted",
"surfaces": [
"router",
"builder_sign_in"
],
"status": 403,
"owner": null,
"summary": "The serving router refuses a WebSocket upgrade whose `Origin` header is neither the origin of the hostname it arrived on nor one that the application's `websockets` declaration lists (MAN-15). The check runs after `standing_stale` and before the visitor's session is read, so a page on another site opens no connection under the visitor's cookie. A handshake with no `Origin` header passes, since every browser sends one. Nothing was forwarded to the application. On the builder sign-in surface, /accounts/v0/tzmesh/site-token refuses an absent Origin or one outside the configured tzMesh site origins, before reading its cookie (ACS-L0-18).",
"remedy": "Open the connection from a page on the application's own hostname, or list the page's origin in the manifest's `websockets.origins` and submit the manifest with submit_manifest. The router reads the declaration within about 30 seconds, with no redeploy. For the tzMesh site token, return to the tzMesh site and sign in there."
},
{
"name": "passkey_already_registered",
"surfaces": [
"builder_sign_in",
"realm_surface"
],
"status": 409,
"owner": "ACC-08",
"summary": "The passkey's credential identifier is already registered in this realm.",
"remedy": "Sign in with the passkey that is already registered, or register again with a different authenticator."
},
{
"name": "passkey_assertion_refused",
"surfaces": [
"builder_sign_in",
"realm_surface"
],
"status": null,
"owner": "ACC-09",
"summary": "The passkey response did not verify: 400 where it cannot be decoded, and 401 where the signature or the user handle fails.",
"remedy": "Start the passkey prompt again from the page that offered it. If a sign-in or a confirmation is refused again, use another sign-in method that page offers."
},
{
"name": "passkey_challenge_unknown",
"surfaces": [
"builder_sign_in",
"realm_surface"
],
"status": 400,
"owner": "ACS-L0-10",
"summary": "The passkey challenge is unknown, already used, or expired, or it was issued for another realm, kind, purpose, or user. A challenge lasts sixty seconds.",
"remedy": "Start the passkey steps again from their options step to get a fresh challenge. Complete them within sixty seconds, on the same realm and for the same user and purpose."
},
{
"name": "passkey_change_closed",
"surfaces": [
"builder_sign_in",
"realm_surface"
],
"status": 409,
"owner": "ACS-L0-10",
"summary": "You asked to revert a passkey change whose seventy-two-hour window has closed, or that was already reverted. Nothing changed.",
"remedy": "Where the change added a passkey that is not yours, remove it on the passkey page, or through the remove routes on an end-user realm, and sign out everywhere. Where the change removed a passkey you want back, register a passkey again. A change is reverted only once."
},
{
"name": "passkey_change_unknown",
"surfaces": [
"builder_sign_in",
"realm_surface"
],
"status": 404,
"owner": "ACS-L0-10",
"summary": "You asked to revert a passkey change that matches no change of your signed-in account or user.",
"remedy": "Read the open changes and pass one of them: on the builder realm, the passkey page lists them; on an end-user realm, the revertible member of GET /__account/passkeys does."
},
{
"name": "passkey_counter_regressed",
"surfaces": [
"builder_sign_in",
"realm_surface"
],
"status": 403,
"owner": "ACC-09",
"summary": "The authenticator's sign count did not go above the stored counter, which can mean a copied authenticator. A counter that stays at zero is accepted.",
"remedy": "For a sign-in or a confirmation, use another sign-in method the page offers. For a removal, confirm it with a different passkey you have."
},
{
"name": "passkey_not_sole_route",
"surfaces": [
"management_action"
],
"status": 400,
"owner": "ACS-L0-10",
"summary": "configure_app_sign_in, or the manifest's realm member through it, gave passkey without email beside it: a passkey is the emailed code's shortcut and no route on its own (ACS-L0-10).",
"remedy": "List email beside passkey, or leave passkey out of the set. To remove email from a set that lists passkey, remove passkey with it; the realm's passkeys are dormant until both return."
},
{
"name": "passkey_not_stranded",
"surfaces": [
"builder_sign_in",
"realm_surface"
],
"status": 409,
"owner": "ACS-L0-10",
"summary": "You asked for the stranded-passkey removal of a passkey that still works on this sign-in host. Use the ordinary removal, which asks you to confirm with the passkey once.",
"remedy": "Remove this passkey through the ordinary removal: the passkey page on the builder realm, or the remove route on an end-user realm. Then complete the passkey confirmation that removal asks for."
},
{
"name": "passkey_origin_mismatch",
"surfaces": [
"builder_sign_in",
"realm_surface"
],
"status": 400,
"owner": "ACS-L0-10",
"summary": "The passkey steps ran, or a page asked for their options, on an origin other than the realm's own sign-in origin.",
"remedy": "Run the passkey steps from a page served on the realm's own sign-in host, then send the response again. For an end-user realm that host is the environment's managed hostname, or its custom domain while production sign-in uses that domain. For the builder realm it is the platform's public sign-in host."
},
{
"name": "passkey_registration_refused",
"surfaces": [
"builder_sign_in",
"realm_surface"
],
"status": 400,
"owner": "ACC-08",
"summary": "The passkey registration did not verify, or its attestation object could not be decoded.",
"remedy": "Start the registration again from your signed-in session and complete the authenticator's user verification when it prompts you. If your authenticator cannot verify you, register with one that can."
},
{
"name": "passkey_requires_email",
"surfaces": [
"builder_sign_in",
"realm_surface"
],
"status": 409,
"owner": "ACS-L0-10",
"summary": "A passkey registration was asked for an account that has no emailed-code sign-in, at the options route or the register route. A passkey is a shortcut for the emailed code, so only an account that signs in by code can have one (ACS-L0-10).",
"remedy": "Sign in by the emailed code once at the address a provider sign-in of this account verified; that adds the code to the account. A code sent to another address makes a new account. Then register the passkey at that sign-in's offer, or later from the platform's passkey page or an application's register route under a fresh authentication."
},
{
"name": "passkey_rp_id_mismatch",
"surfaces": [
"builder_sign_in",
"realm_surface"
],
"status": 400,
"owner": "ACS-L0-10",
"summary": "The authenticator reports a relying-party identifier other than the realm's: its rpIdHash does not match the realm's relying-party identifier hash.",
"remedy": "Run the passkey steps with the relying-party identifier the options step returned, unchanged, from a page on the realm's own sign-in host, then send the response again. If the passkey was registered under an earlier host, sign in by another method and register a new one."
},
{
"name": "passkey_unknown",
"surfaces": [
"builder_sign_in",
"realm_surface"
],
"status": 404,
"owner": "ACC-09",
"summary": "No passkey of this realm matches the credential identifier, or, for an act of a signed-in user, none of that user's does. The passkey's account or user may no longer exist. A passkey whose account has no emailed-code sign-in is refused this way at sign-in too: the platform removes it and opens no session.",
"remedy": "Sign in with a passkey registered on this sign-in host, or by another method the page offers. For a removal, pass a passkey that your signed-in account or user still has. To register a passkey again, sign in by emailed code and accept the offer."
},
{
"name": "passkeys_not_configured",
"surfaces": [
"builder_sign_in"
],
"status": 404,
"owner": "ACS-L0-10",
"summary": "The builder realm's passkey routes are off because the control plane serves no passkey route. Either no relying-party identifier is configured, or no email sender is set up, and a passkey is a shortcut for the emailed code (ACS-L0-10; ACS-L0-07).",
"remedy": "Nothing you do corrects this. Sign in with another method meanwhile. The platform operator configures the relying-party host and the managed sender, and the routes work again once both are set up."
},
{
"name": "picture_ticket_refused",
"surfaces": [
"realm_surface"
],
"status": 403,
"owner": "ACS-L0-25",
"summary": "The accounts service received no live picture ticket for this account and session generation. The ticket is missing, spent, expired, for another account or not at the user's current generation.",
"remedy": "Only the account picture's relay presents this ticket. Sign in again, then repeat the picture action."
},
{
"name": "plan_quantity_unset",
"surfaces": [
"management_action",
"egress",
"push",
"email",
"account_mail"
],
"status": 409,
"owner": "PRC-L0-16",
"summary": "The size's served quantity, or the unlimited plan's quantity, is Unset. An Unset quantity is no row, or a row with no quantity, in the served quota table. It is never read as zero, unlimited, or a default (PRC-L0-02). The refusal gives the quota key and measure. It can refuse create_application with that size, set_app_size onto it, database provisioning, and submit_manifest declaring a schedule. It also refuses deploy, promote, roll_back and restart_application before adding a version where the application's environment has a database.\n\nPush sends and email sends refuse for an unset quantity; for a size, email reads the hour and day cells. An allowance call on the egress surface can refuse for an application on the unlimited plan, never for a size (EGW-L0-06).\n\nThe operator's placement on the unlimited plan refuses where a row for any entry Pro sets is absent or Unset, a served value's among them. A served value's own reader reads an absent row as its default or as no bound. The operator sets the quantity and records the pricing-registry cell.",
"remedy": "Nothing you do sets the quantity. Ask the platform operator to set the quantity for the quota key and measure the refusal gives, then repeat the request.",
"members": {
"plan": {
"type": "string",
"description": "The quota key read: the application's size, or unlimited for the company's applications. A plan name occurs only where pricing reads plans."
},
"measure": {
"type": "string",
"description": "The pricing-registry entry whose quantity is Unset for the key, for example schedule-count-limit."
}
}
},
{
"name": "plan_schedule_conflict",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "SCH-L0-01",
"summary": "The target size's schedule rows, or the unlimited plan's on the operator's placement, do not admit the application's existing schedules. The refusal lists each conflict with its bound. Resubmit the manifest within the target's rows first. Both sizes normally have the same count and interval; a move between sizes meets this refusal only where the operator has set their rows apart.",
"remedy": "Resubmit the manifest through submit_manifest with schedules that fit the target's count limit and minimum interval, then repeat the call.",
"members": {
"plan": {
"type": "string",
"description": "The quota key read: the application's size, or unlimited for the company's applications. A plan name occurs only where pricing reads plans."
},
"schedules": {
"type": "array",
"description": "One entry per conflict between an existing schedule and the target key. The list is never empty, and one schedule appears once per measure it violates.",
"items": {
"type": "object",
"properties": {
"schedule": {
"type": "string",
"description": "The schedule's declared name."
},
"measure": {
"type": "string",
"description": "The measure violated: schedule-minimum-interval or schedule-count-limit."
},
"bound": {
"type": "integer",
"description": "The target key's served quantity for that measure: minutes for the interval, a count for the limit."
},
"cron": {
"type": "string",
"description": "The schedule's cron expression as recorded."
},
"gap": {
"type": "integer",
"description": "The shortest gap in whole minutes between the expression's consecutive due times, on an interval entry alone."
}
}
}
}
}
},
{
"name": "platform_credential_required",
"surfaces": [
"push",
"email"
],
"status": 403,
"owner": "PSH-L0-03",
"summary": "A send arrived under a session or a minted token. The send route accepts only the application's platform credential, which identifies the application and fixes the environment.",
"remedy": "Send from your backend under the platform credential, the value of TURNZERO_CLOUD_APP_TOKEN in the environment file."
},
{
"name": "platform_credential_unreadable",
"surfaces": [
"management_action"
],
"status": 502,
"owner": "SEC-L0-07",
"summary": "deploy or restart: the environment has an existing platform credential, and its value could not be read from custody. The act is refused rather than run under a credential the platform cannot inject.",
"remedy": "For the development environment, run `turnzero provision --application <application id>` with nothing piped, adding `--origin` where your other lines include one, and make any call it prints. Its line re-mints the development platform credential into custody. Then deploy again. If the refusal repeats, report it with its detail. For production, report it and quote its `reference` and `detail`; platform staff must restore the production credential."
},
{
"name": "platform_minted_name",
"surfaces": [
"management_action",
"egress"
],
"status": 409,
"owner": "SEC-L0-07",
"summary": "A call used the name of a credential the platform minted for one of your account's applications (SEC-L0-07; ITS-L0-01; EGW-L0-01; MAN-14). The refusing calls are store_secret, delete_secret, configure_app_sign_in, configure_push, declare_outbound_api, and a `settings` binding at submit_manifest, deploy, or promote. The platform mints three: the database credential `database-<application id>`, the platform credential `credential-<application id>`, and the issue-tracking token `issue-tracking-<application id>`. The call was refused before any write. On the egress surface, a call through a declaration that uses one is refused before any custody read, so no declared upstream presents a value the platform minted. A platform-minted name stays the platform's to rotate. A realm's client secret or Apple signing key is a name you stored (ACS-L0-09). On the development scope alone, store_secret with replace: true re-mints the first two, never under a store or a rotate grant, and it refuses the issue-tracking token at every scope. The delete_secret action refuses all three at every scope, since each ends with its environment, application, or account.",
"remedy": "Pass store_secret a name of your own, and use that name in configure_app_sign_in, configure_push, declare_outbound_api, or a manifest binding. To re-mint a development credential, run `turnzero provision --application <application id>` with nothing piped, adding `--origin` where your other lines include one, and make any call it prints. Its line calls store_secret with replace: true on the development scope. To rotate a production credential, call promote, with rotate_database_credential true for the database credential. A call refused at the gateway succeeds once the upstream is declared again under a name of your own. Include the upstream's `sdk_settings` in that call, or omit the member, which keeps them; `sdk_settings` null removes them and ends the upstream's egress keys.",
"members": {
"application": {
"type": "string",
"description": "The id of the account's application whose platform-minted credential name the request used."
}
}
},
{
"name": "platform_space_configure_refused",
"surfaces": [
"management_action"
],
"status": 403,
"owner": "ITS-L0-05",
"summary": "relay_issue_act asked for configure on the platform's own space, under a credential at the owner level. No level allows that act there, and nothing was changed: the platform's operator configures that space.",
"remedy": "Nothing you do corrects this. Every other act your credential's level allows still reaches the space. The platform's operator makes any change to the space's configuration.",
"members": {
"space": {
"type": "string",
"description": "The space the request gave."
}
}
},
{
"name": "pod_create_refused",
"surfaces": [
"management_action"
],
"status": 503,
"owner": "PLD-L0-63",
"summary": "deploy, promote, or restart on the pod grain: the cluster refused to create the candidate's pod, so nothing ran to serve the health path. The health gate ended once two consecutive reads found the refusal in place, rather than at its 180-second bound. The candidate is deleted, and the serving compute and the previous version are untouched. The history row ends failed at the step health_gate with this outcome and no gate member, since no pod existed to probe or read.",
"remedy": "Nothing in the application caused it: deploy again later. Where it repeats, report it with the act's reference; the platform's operator reads the cluster's reason on the control plane's record of the failed version."
},
{
"name": "product_ticket_refused",
"surfaces": [
"realm_surface"
],
"status": 403,
"owner": "MAPI-23",
"summary": "The accounts service's product-token signing route received no live product_token ticket for the account and product: the ticket is missing, spent, expired, or for another account or product.",
"remedy": "Nothing you call corrects this. Only the token code's exchange presents a ticket, so mint the token again."
},
{
"name": "progress_window_ended",
"surfaces": [
"deploy_progress"
],
"status": 403,
"owner": "PLD-L0-86",
"summary": "The deploy command read a deploy's progress under its started upload grant outside the read's window. The window runs until five minutes after the deploy ends, and never past fifteen minutes after the start. A grant has no window where its start was refused, or where a later preparing `deploy` call replaced its upload.",
"remedy": "Read the deploy with `read_status` from your tool, giving the application and the environment the deploy went to. Pass `wait_seconds` where the deploy is still running."
},
{
"name": "provider_not_enabled",
"surfaces": [
"realm_surface"
],
"status": 400,
"owner": "ACS-L0-14",
"summary": "The token exchange's ID token is Apple's or Google's, and the realm does not enable that issuer's route: apple for Apple, google for Google.",
"remedy": "If you are the application's author, add the route to the realm's sign_in_methods with configure_app_sign_in, the apple route together with its apple member. The read_app_sign_in action shows the enabled set."
},
{
"name": "proxy_authentication_required",
"surfaces": [
"egress_tunnel"
],
"status": 407,
"owner": "EGW-L0-16",
"summary": "The tunnel proxy received no proxy credential, or one that matches no application. Your application's platform credential is the proxy credential.",
"remedy": "Send your application's platform credential in the Proxy-Authorization header on every tunnel establishment."
},
{
"name": "publication_bounded",
"surfaces": [
"management_action"
],
"status": 403,
"owner": "MAPI-16",
"summary": "You called an action outside the bound of a minted token that has the publication grant and no super_admin. The grant limits its token to the actions it marks, the two publishing actions. The actions marked access: anonymous are outside the bound and serve the token as they serve every connection.",
"remedy": "Call the action from the owner's signed-in session, or under a token minted through mint_token without the publication grant. The refusal's `admitted` member lists the actions the bounded token can reach.",
"members": {
"grant": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]*$",
"description": "The grant that bounds the credential presented."
},
"admitted": {
"type": "array",
"items": {
"type": "string"
},
"description": "The actions the bound admits, in the enumeration's order: the rows the grant marks and the rows whose admits mark lists it. The rows marked access: anonymous lie outside the bound and are not listed."
}
}
},
{
"name": "publish_incomplete",
"surfaces": [
"management_action"
],
"status": 409,
"owner": null,
"summary": "At the commit of a library publish, blobs the catalog lists are not in the store. At the commit of a public-files publish, versioned names the manifest lists are not in the container. In both, the refusal's `missing` member lists the missing ones.",
"remedy": "Run `put` for each blob or file the refusal lists as missing, or that `begin` returned as lacking, then run `commit` again.",
"members": {
"missing": {
"type": "array",
"items": {
"type": "string"
},
"description": "What the commit lists and the puts never wrote, never empty. For a library publish each entry is a blob's sha256. For a public-files publish each entry is a file name, or a site-relative path for the site."
}
}
},
{
"name": "publish_not_forward",
"surfaces": [
"management_action"
],
"status": 409,
"owner": null,
"summary": "At the commit of a library publish, a source commit other than the served one gave a `served_commit` that is absent or stale, no longer the served commit. At its begin, a catalog for the served commit differs from the one served. Both refuse the publish. At the begin or commit of a public-files publish, the container's served version is newer than the committed one under the numeric triple comparison. For the packages container the rule is read per package: a served package's newest version is greater than the incoming one, or a served package is absent from the incoming manifest. At commit, the publish is also refused where the stable manifest's version moved between the read and the conditional write, so of two overlapping publishers one commits and the other writes nothing.",
"remedy": "For a library publish, read the served commit again, check the publishing commit descends from it, and commit with it as `served_commit`; publish a changed catalog from a newer commit. Where the served version or commit is newer than yours, publish again from a trunk head ahead of it, keeping every served package in the manifest. Where another publisher committed during yours, run `begin` again and then `commit` again, for the site container with the sequence `begin` now returns plus one."
},
{
"name": "published_bytes_differ",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "PLD-L0-68",
"summary": "A public-files publish's begin, put, or commit: a versioned name already exists in the container with a different sha256 in its blob metadata. The refusal gives the file. A versioned file is never rewritten once published.",
"remedy": "Publish under a new version: a new release, a new package version, or a new site source commit. Do not retry the same version with different bytes.",
"members": {
"file": {
"type": "string",
"description": "The published versioned name whose recorded sha256 differs from the incoming file's. For the site it is the full versioned name, the source commit's folder included."
}
}
},
{
"name": "purchase_limit_reached",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "ACB-L0-102",
"summary": "The account's purchases paid in this UTC day, plus the amount requested, exceed its daily limit. No checkout was opened and nothing was charged.",
"remedy": "Request a smaller amount from the enumeration if it fits, or wait for the next UTC day."
},
{
"name": "purchase_not_admitted",
"surfaces": [
"management_action"
],
"status": 403,
"owner": "ACB-L0-102",
"summary": "The account cannot buy credit. No checkout was opened and nothing was charged. The reason identifies the admission check.",
"remedy": "For an unbilled account, credit purchases are not available. For a flag, contact support. For an open dispute, wait until it is settled. A test-mode site admits synthetic and operator accounts alone.",
"members": {
"reason": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]*$",
"description": "The account is unbilled, blocked after a refund or dispute, holds an open payment dispute, or is an ordinary account on a site that takes test payments only."
}
}
},
{
"name": "purchase_rate_limited",
"surfaces": [
"management_action"
],
"status": 429,
"owner": "ACB-L0-102",
"summary": "The account has reached the limit on credit purchase starts. No checkout was opened and nothing was charged.",
"remedy": "Wait before starting another credit purchase. Choosing a smaller amount does not avoid this limit."
},
{
"name": "purchase_unavailable",
"surfaces": [
"management_action"
],
"status": 503,
"owner": "ACB-L0-101",
"summary": "The call returned no checkout link: the site's purchase routes are closed, the provider failed, the provider's price differs, or another start replaced this one.",
"remedy": "Try again later. With reason replaced, use the newer checkout or request a new one.",
"members": {
"reason": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]*$",
"description": "Present as replaced if another purchase start for this account replaced this one; absent for other causes."
}
}
},
{
"name": "push_not_configured",
"surfaces": [
"push"
],
"status": 409,
"owner": "PSH-L0-03",
"summary": "A send reached an environment that has no push provider configured.",
"remedy": "Store the provider's credential, the Apple signing key or the Google service-account file, with store_secret for the application and the environment. Then call configure_push with it, and send again."
},
{
"name": "push_not_declared",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "PSH-L0-01",
"summary": "configure_push or read_push was called for an application whose recorded manifest declares no push service.",
"remedy": "Add {\"kind\": \"push\"} to the manifest's services and resubmit it with submit_manifest, then repeat the request."
},
{
"name": "query_failed",
"surfaces": [
"management_action"
],
"status": null,
"owner": "DBS-L0-11",
"summary": "query_database: the statement or its session failed, and nothing was changed. Where the server returned a SQLSTATE, at login or after, the status is 422, and the refusal includes `sqlstate` and the server's message, cut to 300 characters. Among them are 42601 for a second statement or a SELECT INTO, 57014 for the 10-second statement timeout, 53300 for the role's connection limit, and 28P01 for a refused login. Where none was returned, as for a connect timeout, TLS, or the network, the status is 503 with a fixed sentence, and the platform retries nothing.",
"remedy": "For a 422, read `sqlstate` and the message and correct the statement: send one statement with no INTO, and narrow one that passes the 10-second timeout with WHERE or LIMIT. For 53300, call again once your application's pool frees a connection. For a 503, call again; where it repeats, or for 28P01, report it with submit_feedback, quoting the reference.",
"members": {
"sqlstate": {
"type": "string",
"description": "The five-character SQLSTATE the server returned, on a 422 alone."
}
}
},
{
"name": "query_not_read_only",
"surfaces": [
"management_action"
],
"status": 400,
"owner": "DBS-L0-11",
"summary": "query_database: the statement's first word is not SELECT, WITH, VALUES, or TABLE, and the detail quotes the word. Or the server refused a write the statement makes anywhere beneath it, in a function it calls or through nextval() (SQLSTATE 25006). Or the cursor's declaration refused a data-modifying WITH (SQLSTATE 0A000). Nothing was changed: the transaction is read-only and always rolled back.",
"remedy": "Send a statement that only reads, starting with SELECT, WITH, VALUES, or TABLE. Change data through your application's own code or migrations, deployed as usual. Read a setting with current_setting('<name>') in place of SHOW."
},
{
"name": "rate_capped",
"surfaces": [
"management_action",
"realm_surface",
"builder_sign_in",
"storage",
"egress",
"router",
"logging",
"push",
"email",
"deploy_progress",
"workflow_start",
"mcp_server",
"documentation",
"support_read",
"account_mail",
"dashboard_picture",
"payment_event"
],
"status": 429,
"owner": "PLD-L0-67",
"summary": "Too many requests came from one source within the window. The bound is an application's logging batches per minute, a source address's client registrations per hour, or its requests per minute to the control plane or on router resolve misses (the admission window). Every request to the control plane counts once by its source address. A page view of the site counts in a page window of its own, six hundred a minute. A call to read_library on the actions route counts in a library window of its own, four thousand a minute. A call to search_documentation presenting no credential counts in a documentation search window of its own, one hundred and twenty a minute. Every other request counts in the source window, six hundred a minute. A signed-in approval or dashboard arrival spends no source window. On the storage, egress, logging, and push wires, a request whose presented credential resolves counts in a window keyed on that credential's identity and not on the source address. A presented value there that resolves to no credential counts in a window of its own for the source, six hundred a minute, apart from the source window. On those wires, a request through the edge whose source is at that bound is refused before its credential is looked up, unless the gateway already has that credential. On the deploy command's progress read, a read under its upload's started grant counts in a window keyed on that grant's identity. A read there that presents anything else counts in the source window, which once full refuses the source before any lookup. At the control plane, the admission window's refusal includes Retry-After, the seconds to the next minute. The serving router also refuses with rate_capped a source past its bound of requests per minute to one application on one router replica (SVC-L0-18). That refusal comes before the request reaches the application, and its Retry-After gives the seconds to the next minute. A `request_route` or `write_route` call counts in one window of their own for the acting account, sixty a minute (MAPI-28). A `check_app_sign_in` call counts in a window of its own for the acting account, ten a minute, and the accounts service counts the checks of each realm in a window of its own, ten a minute.\n\nFor the dashboard picture route, an arrival without a verified dashboard cookie and current session uses the source window; an admitted arrival counts in its account's own window, sixty reads a minute.",
"remedy": "Wait for the window to pass, the number of seconds in Retry-After where the response includes it, then repeat the request at a rate under the limit. The window is one minute for requests and logging batches and one hour for client registrations."
},
{
"name": "rates_unread",
"surfaces": [
"management_action"
],
"status": 503,
"owner": "ACB-L0-26",
"summary": "Turning on the monthly option needed a new charge, but the platform could not read the rates in effect. The option stays off and nothing was charged.",
"remedy": "Try turning the option on again shortly. If the refusal repeats, report it with its detail."
},
{
"name": "realm_check_unavailable",
"surfaces": [
"management_action"
],
"status": 503,
"owner": "MAPI-30",
"summary": "check_app_sign_in reached a platform service that cannot complete the realm check: the service that reads a realm's sign-in credentials did not answer within twelve seconds, or did not accept the call. Nothing was checked.",
"remedy": "Call check_app_sign_in again. read_app_sign_in returns the realm's configuration meanwhile."
},
{
"name": "realm_check_unmarked",
"surfaces": [
"realm_surface"
],
"status": 404,
"owner": "ACS-L0-24",
"summary": "The accounts service's realm check route serves only the management service's own marked call from inside the plane. This request carried no mark or a wrong one, or came through the edge.",
"remedy": "Nothing you send marks the request. Check a realm with check_app_sign_in, and the platform runs the check for you."
},
{
"name": "realm_creation_ceiling",
"surfaces": [
"realm_surface",
"builder_sign_in"
],
"status": 403,
"owner": "ACS-L0-07",
"summary": "On a creation, the realm accepts no further accounts: the creation ceiling is reached. On the platform's own builder sign-in, the name is recorded on the operator's side, and your page shows the operator's paused panel and no name.",
"remedy": "On an end-user realm's creation, nothing the person signing up does corrects this: you, the application's author, raise the ceiling with configure_app_sign_in (limits.creation_ceiling). On the platform's own builder sign-in, the operator raises or clears it the same way, and an invitation's link still creates an account."
},
{
"name": "realm_keys_unready",
"surfaces": [
"management_action",
"realm_surface"
],
"status": 503,
"owner": "PLD-L0-67",
"summary": "The accounts instance has not yet unwrapped the realm's key-encryption key. The re-issue route refuses with it, and so does the token code's exchange, whose product token could not be signed for the same reason (MAPI-23).",
"remedy": "Retry the request; at the token code's exchange, mint again. If the refusal repeats, report it with its detail."
},
{
"name": "realm_not_declared",
"surfaces": [
"management_action",
"realm_surface",
"push"
],
"status": 404,
"owner": "MAN-03",
"summary": "The application declares no accounts kind, or no application that declares one has the forwarded host. On the builder form of a realm action, the builder realm row is absent from the store, on an estate that has not yet run migration 0022 (ACS-L0-01). On submit_manifest, a realm ended between the submission's check and its record, so it was not configured. The manifest stays recorded, and the detail lists the realms done and those not. On create_environment, development's realm ended while the act recorded the realm member.",
"remedy": "Add {\"kind\": \"accounts\"} to the manifest's services and resubmit it with submit_manifest, then repeat the request. On the builder-realm form, where the platform's own schema migration alone creates the builder realm, nothing you do corrects this. On submit_manifest, submit the manifest again, which configures each realm the application has. On create_environment, call it again."
},
{
"name": "realm_state_required",
"surfaces": [
"realm_surface"
],
"status": 400,
"owner": "ACS-L0-04",
"summary": "A handoff was redeemed in a browser that presents no state cookie for the sign-in that started.",
"remedy": "Start the sign-in again from the application's sign-in page and complete it in that same browser without delay."
},
{
"name": "realm_surface_unmarked",
"surfaces": [
"realm_surface"
],
"status": 404,
"owner": "ACS-L0-04",
"summary": "The realm surface serves only the requests the serving router forwards with its mark.",
"remedy": "Send the request to the application's own hostname under the /__account/ prefix, so the serving router forwards it. No header you add marks the request."
},
{
"name": "realm_vault_unregistered",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "ACS-L0-09",
"summary": "configure_app_sign_in: the application's cell registers no realm vault, so the client secret or the Apple signing key has no vault to move into.",
"remedy": "Nothing you do corrects this. Report it to the platform's operator, whose register write fills the cell's row."
},
{
"name": "reauthentication_not_fresh",
"surfaces": [
"realm_surface"
],
"status": 403,
"owner": "ACS-L0-05",
"summary": "A provider sign-in started for the fresh authentication came back from a provider that reports the end user last signed in with it more than five minutes ago. So it proves no fresh act of theirs (ACS-L0-05). Nothing was signed in.",
"remedy": "Have the end user sign in to the provider again, then start the reauthentication once more. An emailed code or a passkey assertion also gives the fresh authentication."
},
{
"name": "reauthentication_other_account",
"surfaces": [
"realm_surface"
],
"status": 403,
"owner": "ACS-L0-05",
"summary": "A reauthentication completed for an identity that resolves to a user other than the starting session's user, or to no user (ACS-L0-05). Nothing was signed in and no user was created.",
"remedy": "Start the reauthentication again under the end user's own session, and choose the same account at the provider as the one signed in to the application."
},
{
"name": "refresh_reused",
"surfaces": [
"realm_surface"
],
"status": 400,
"owner": "ACS-L0-14",
"summary": "A refresh credential that the token endpoint replaced more than sixty seconds ago was presented again. As a precaution against a stolen copy, the native session is ended: its row ended and its revocation written together.",
"remedy": "Sign in again from the app. Keep one refresh credential per installed app, replace it with the one each response gives, and never copy it between devices or processes."
},
{
"name": "refund_not_admitted",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "ACB-L0-104",
"summary": "This purchase is not eligible for this refund. The reason and refund conditions explain the refusal. This call requested no refund and removed no credit.",
"remedy": "For reason_required, read conditions and supply a reason if the operator chooses to ask again. For refunding, wait for the recorded refund; for refunded, stop. Disputed, never-paid or past-reach purchases cannot be refunded here. For provider_closed, the operator must reopen the estate’s payment routes before asking again.",
"members": {
"reason": {
"description": "The first failed admission check: purchase state, absolute reach, required reason, then provider availability. Current values include `refunded`, `refunding`, `disputed`, `never_paid`, `past_reach`, `reason_required`, `provider_closed`.",
"type": "string"
},
"account": {
"type": "object",
"description": "The account whose purchase or flag is being handled.",
"properties": {
"id": {
"type": "string",
"description": "The account id."
}
}
},
"purchase": {
"type": "object",
"description": "The purchase and its payment/refund state; no provider identifier.",
"properties": {
"id": {
"type": "string",
"description": "The purchase id."
},
"state": {
"description": "`started`: checkout opened, no grant; `paid`: its grant was issued; `expired`: checkout abandoned or payment failed. `refunding` and `refunded`: a refund on its way and done. `disputed`: a dispute removed the grant's remainder. `dispute_lost`: the dispute closed against the seller, and credit stays removed. A dispute closed in the seller's favour returns the purchase to `paid`.",
"type": "string"
},
"amount": {
"type": "string",
"description": "The purchase amount before tax, as a dollars string. A dollars string starts with a dollar sign, separates thousands with commas and is rounded to two decimal places. A positive amount below one cent is rounded to four."
},
"amount_micros": {
"type": "integer",
"description": "The purchase amount before tax in whole micro-dollars, zero or greater."
},
"currency": {
"type": "string",
"description": "The purchase's currency."
},
"paid_at": {
"type": [
"string",
"null"
],
"description": "The payment's instant, where known."
},
"refunded_at": {
"type": [
"string",
"null"
],
"description": "The refund's instant, where recorded."
},
"refund_micros": {
"type": [
"integer",
"null"
],
"description": "The refunded amount in whole micro-dollars, zero or greater, or null where none."
}
}
},
"conditions": {
"type": "object",
"description": "The three conditions as read at the act.",
"properties": {
"within_window": {
"type": "boolean",
"description": "The act's instant is within the refund window from payment."
},
"unspent": {
"type": "boolean",
"description": "Usage has drawn nothing of this purchase's grant."
},
"first_in_span": {
"type": "boolean",
"description": "No other operator refund, completed or under way, counts in the frequency span."
}
}
},
"within_rule": {
"type": "boolean",
"description": "All three refund-rule conditions hold."
},
"within_reach": {
"type": "boolean",
"description": "The payment is within the absolute refund reach."
}
}
},
{
"name": "refund_refused",
"surfaces": [
"management_action"
],
"status": 502,
"owner": "ACB-L0-104",
"summary": "The payment provider refused the approved refund. The answer says whether removed credit was restored; a purchase changed by a dispute may prevent restoration.",
"remedy": "Read restored and the purchase state before deciding what to do next. Keep provider_status and provider_code for diagnosis. Do not retry blindly or clear a flag as a substitute for a refund.",
"members": {
"account": {
"type": "object",
"description": "The account whose purchase or flag is being handled.",
"properties": {
"id": {
"type": "string",
"description": "The account id."
}
}
},
"purchase": {
"type": "object",
"description": "The purchase and its payment/refund state; no provider identifier.",
"properties": {
"id": {
"type": "string",
"description": "The purchase id."
},
"state": {
"description": "`started`: checkout opened, no grant; `paid`: its grant was issued; `expired`: checkout abandoned or payment failed. `refunding` and `refunded`: a refund on its way and done. `disputed`: a dispute removed the grant's remainder. `dispute_lost`: the dispute closed against the seller, and credit stays removed. A dispute closed in the seller's favour returns the purchase to `paid`.",
"type": "string"
},
"amount": {
"type": "string",
"description": "The purchase amount before tax, as a dollars string. A dollars string starts with a dollar sign, separates thousands with commas and is rounded to two decimal places. A positive amount below one cent is rounded to four."
},
"amount_micros": {
"type": "integer",
"description": "The purchase amount before tax in whole micro-dollars, zero or greater."
},
"currency": {
"type": "string",
"description": "The purchase's currency."
},
"paid_at": {
"type": [
"string",
"null"
],
"description": "The payment's instant, where known."
},
"refunded_at": {
"type": [
"string",
"null"
],
"description": "The refund's instant, where recorded."
},
"refund_micros": {
"type": [
"integer",
"null"
],
"description": "The refunded amount in whole micro-dollars, zero or greater, or null where none."
}
}
},
"conditions": {
"type": "object",
"description": "The three conditions as read at the act.",
"properties": {
"within_window": {
"type": "boolean",
"description": "The act's instant is within the refund window from payment."
},
"unspent": {
"type": "boolean",
"description": "Usage has drawn nothing of this purchase's grant."
},
"first_in_span": {
"type": "boolean",
"description": "No other operator refund, completed or under way, counts in the frequency span."
}
}
},
"within_rule": {
"type": "boolean",
"description": "All three refund-rule conditions hold."
},
"within_reach": {
"type": "boolean",
"description": "The payment is within the absolute refund reach."
},
"restored": {
"type": "boolean",
"description": "True if the purchase returned to paid with its removed credit restored."
},
"provider_status": {
"type": [
"integer",
"null"
],
"description": "The provider’s HTTP refusal status, where available."
},
"provider_code": {
"type": [
"string",
"null"
],
"description": "The provider’s refusal code, where available."
}
}
},
{
"name": "refused_base_url",
"surfaces": [
"egress"
],
"status": 400,
"owner": "EGW-L0-08",
"summary": "The declared upstream's base URL is refused at the call. It is not https, contains a user name or password, or uses an outbound mail port. Or its host is a loopback, metadata, or internal name, or an address outside public unicast. Declare the upstream again.",
"remedy": "Correct the base URL to an https address on a public host, then run declare_outbound_api again under the same upstream name. Include the upstream's `sdk_settings` in that call, or omit the member, which keeps them; `sdk_settings` null removes them and ends the upstream's egress keys. A base URL on an outbound mail port (25, 465, 587, or 2525) is refused as well. Send mail through a mail provider's HTTPS API, declared as an upstream. Where the upstream is ai-allowance or issue-tracking, its base URL is a platform setting, so report the refusal with its detail."
},
{
"name": "refused_platform_host",
"surfaces": [
"management_action",
"egress"
],
"status": 400,
"owner": "EGW-L0-01",
"summary": "declare_outbound_api, and the egress gateway at each call: the base URL's host is one of the platform's own, which no declared upstream can reach. The platform's own hosts are its vaults, its storage accounts, its container registries, its own service hostnames, and the management and sign-in endpoints of the provider the platform runs on. The detail gives the host. The refusal is by hostname and never by a provider's domain, so your own vault, storage account, or registry at the same provider is accepted.",
"remedy": "Declare the upstream against a host of your own, then run declare_outbound_api again under the same upstream name. No declaration reaches one of the platform's own hosts, and nothing you do changes that. Include the upstream's `sdk_settings` in that call, or omit the member, which keeps them; `sdk_settings` null removes them and ends the upstream's egress keys."
},
{
"name": "region_unavailable",
"surfaces": [
"management_action"
],
"status": 400,
"owner": "PLD-L0-22",
"summary": "submit_manifest: the region is europe, uk, or global, which the schema accepts. Only the usa region is offered during our introductory period, and any other value fails the schema as manifest_invalid.",
"remedy": "Set the manifest's region to usa, then call submit_manifest again. Nothing you do makes another region available, because only the platform adds a region to the set it serves.",
"members": {
"region": {
"type": "string",
"description": "The region the submitted manifest declares, one the platform does not offer yet."
}
}
},
{
"name": "renamed",
"surfaces": [
"mcp_server"
],
"status": 404,
"owner": "MCP-14",
"summary": "The call used a product tool's former prefixed name, which the product's server no longer serves. This connection lists that product's tools. Nothing was done. The detail gives each replacement's name as this connection lists it.",
"remedy": "Call the replacement `detail` gives. If `detail` lists several, read their descriptions and choose the tool that matches your task."
},
{
"name": "request_too_large",
"surfaces": [
"storage",
"egress",
"builder_sign_in",
"management_action",
"mcp_server",
"realm_surface",
"push",
"email",
"router",
"workflow_start",
"account_mail",
"payment_event"
],
"status": 413,
"owner": "EGW-L0-05",
"summary": "The request is over the surface's request bound, or over the bound a transfer grant accepts (OST-L0-04 on storage). On the builder sign-in, a client registration's declared body is over 16 KiB (PLD-L0-67). On every surface, the serving router among them, a body over the bound the surface's parser reads is refused the same way, the detail giving that bound (PLD-L0-95).",
"remedy": "Reduce the request body to the byte bound the refusal detail gives, then send it again. Keep a storage upload within the size its transfer grant accepts, and keep a client registration at sign-in at or under 16 KiB."
},
{
"name": "reserved_upstream_name",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "EGW-L0-01",
"summary": "declare_outbound_api was called with a reserved upstream name, ai-allowance or issue-tracking, which belongs to the platform and no account declares. Choose another name.",
"remedy": "Declare the upstream under another name with declare_outbound_api. To use the included AI allowance, call the platform upstream ai-allowance without declaring it. To reach the application's issue-tracking space, call the platform upstream issue-tracking without declaring it."
},
{
"name": "response_too_large",
"surfaces": [
"egress"
],
"status": 502,
"owner": "EGW-L0-05",
"summary": "The upstream's response is larger than the gateway's response limit. A streamed response is cut before the chunk that crosses the limit, and ends with this refusal as its final event.",
"remedy": "Request a smaller response from the upstream, using paging where it offers paging."
},
{
"name": "retired_host",
"surfaces": [
"builder_sign_in",
"egress",
"logging",
"management_action",
"mcp_server",
"realm_surface",
"storage",
"documentation",
"push",
"email",
"account_mail"
],
"status": 421,
"owner": "PLD-L0-67",
"summary": "The hostname you sent the request to is one the platform retired. The request is refused before any route runs, and the detail gives the current address. A client that still uses the old name fails with a clear reason instead of working on it unnoticed.",
"remedy": "Change the address your client uses to the current address the detail gives, then send the request again."
},
{
"name": "rotation_in_flight",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "DBS-L0-02",
"summary": "store_secret with replace: true, re-minting the development database credential, waited for another re-mint of the same role. That re-mint kept the role's lock on the cell server longer than the platform waits, so nothing was changed: the role keeps its password, and custody keeps its value.",
"remedy": "Wait for the other store_secret with replace: true call to finish, then call store_secret with replace: true again. Each call returns its own value, and the value of the call that ends last is the one the role and custody keep. A fresh provision line writes the value that remains: run `turnzero provision --application <application id>` with nothing piped, adding `--origin` where your other lines include one, and make any call it prints.",
"members": {
"application": {
"type": "string",
"description": "The id of the application whose development database credential the call asked to re-mint."
}
}
},
{
"name": "route_not_enabled",
"surfaces": [
"management_action",
"realm_surface"
],
"status": 400,
"owner": "ACS-L0-07",
"summary": "The requested route is not in the realm's effective set, or its provider is not configured on this server. The `sign_in_test_end_user` action returns it where the realm's effective set is empty, which allows no sign-in, not even a test end user's, and nothing is signed in.",
"remedy": "Sign in through a route the realm has enabled. If you are the application's author, enable a route with configure_app_sign_in; read_app_sign_in shows the enabled set. The platform's operator configures a provider that the server lacks."
},
{
"name": "route_set_contradicts_audience",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "ADM-L0-05",
"summary": "configure_app_sign_in: a workforce realm was given a passwordless route, or an Entra tenant other than the declared one.",
"remedy": "Call configure_app_sign_in again with only the work-account route, entra, and the tenant the manifest declares. To allow a passwordless route or another tenant, change the manifest's audience or its declared tenant with submit_manifest first.",
"members": {
"audience": {
"type": "string",
"description": "The audience the application's recorded manifest declares, workforce at this refusal."
},
"tenant": {
"type": "string",
"description": "The Entra tenant the manifest declares, present only where the call gave a different tenant."
}
}
},
{
"name": "route_unreachable",
"surfaces": [
"management_action"
],
"status": 502,
"owner": "MAPI-28",
"summary": "A `request_route` or `write_route` call could not be completed. Its managed hostname resolved to no address or to one outside public unicast, the connection or its TLS failed, or the call passed its 20 seconds. The platform makes no connection to an address outside public unicast, and `reason` gives the cause.",
"remedy": "Where `reason` is `timeout`, `connect_failed` or `tls_failed`, check read_status for a serving version and read_logs for application errors. For `write_route` after `timeout` or `connect_failed`, first read the resource with request_route or inspect read_logs; repeat only if that read confirms the write did not take effect. A read or a `tls_failed` call may be repeated after those checks. Where it is `no_address` or `address_not_public`, report it with the detail and the reference: the platform's own hostname did not resolve as it should.",
"members": {
"reason": {
"type": "string",
"description": "Why the route was not reached: `no_address`, the hostname resolved to no address; `address_not_public`, it resolved outside public unicast. Or `connect_failed`, the connection failed or ended before the body was read; `tls_failed`, the TLS connection failed; or `timeout`, the call passed its 20 seconds."
}
}
},
{
"name": "router_mark_required",
"surfaces": [
"harness"
],
"status": 403,
"owner": "HST-L0-01",
"summary": "The runtime harness refused a request that reached the application's provider default hostname without the router's mark, or with a mark the container does not have. Only the serving router reaches an application (SVC-L0-07). The way in is the managed hostname, through the serving router.",
"remedy": "Send the request to the application's managed hostname on ai.host instead of the provider default hostname. Where your application calls itself from inside its own container, use the loopback address, which needs no mark."
},
{
"name": "run_in_flight",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "SCH-L0-06",
"summary": "A run of the schedule is still running. A schedule has at most one run in flight, and a due time during it is skipped rather than queued.",
"remedy": "Wait until read_schedules shows no run in flight for the schedule, then call run_schedule again."
},
{
"name": "schedule_count_over_plan",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "SCH-L0-01",
"summary": "The manifest declares more schedules than the size's `schedule-count-limit` row allows. The refusal gives the first declaration past the count.",
"remedy": "Remove schedule declarations until the count is within the size's limit, then call submit_manifest again. Both sizes have the same count limit.",
"members": {
"path": {
"type": "string",
"description": "The JSON path of the first schedule declaration past the size's count."
},
"plan": {
"type": "string",
"description": "The quota key read: the application's size, or unlimited for the company's applications. A plan name occurs only where pricing reads plans."
},
"measure": {
"type": "string",
"description": "The measure the refusal is keyed on, schedule-count-limit."
},
"quantity": {
"type": "integer",
"description": "The size's served count limit, the most schedules the application may declare."
}
}
},
{
"name": "schedule_interval_below_plan",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "SCH-L0-01",
"summary": "A declared schedule's consecutive due times are closer together than the size's `schedule-minimum-interval` row allows. The refusal gives the declaration's path and the floor.",
"remedy": "Lengthen the refused schedule's cron expression to meet the size's minimum interval, then call submit_manifest again. Both sizes have the same minimum interval.",
"members": {
"path": {
"type": "string",
"description": "The JSON path of the cron expression whose due times fall too close together."
},
"plan": {
"type": "string",
"description": "The quota key read: the application's size, or unlimited for the company's applications. A plan name occurs only where pricing reads plans."
},
"measure": {
"type": "string",
"description": "The measure the refusal is keyed on, schedule-minimum-interval."
},
"quantity": {
"type": "integer",
"description": "The size's served minimum interval in minutes, the floor."
},
"gap": {
"type": "integer",
"description": "The shortest gap in whole minutes between the expression's consecutive due times, less than the floor."
}
}
},
{
"name": "schedule_not_deployed",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "SCH-L0-06",
"summary": "The environment has no version deployed or promoted at or after the schedule's declaration, so the schedule cannot fire there. Deploy to it first, or promote to production on an application with two environments.",
"remedy": "Deploy to that environment, or promote to production on an application with two environments, then call run_schedule again. The read_schedules action shows whether each schedule still awaits a deploy."
},
{
"name": "scheduled_handler_only",
"surfaces": [
"harness",
"router"
],
"status": 404,
"owner": "HST-L0-06",
"summary": "This declared schedule path accepts only the platform's scheduled runs. The harness or function pool refuses other requests before your application's code runs. The harness records a harness_refusal line.",
"remedy": "Only the platform's scheduled runs reach that path; call run_schedule to start one now. To make the path public, remove that schedule from the manifest and submit it with submit_manifest, then deploy or promote the environment again."
},
{
"name": "scope_fixed",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "SCRT-L0-08",
"summary": "store_secret gave a scope the name may not share with the scope it is at. A name at an application's scope cannot move to the account scope or to another application's scope, and a name at the account scope cannot move to an application's scope. An application's two environment scopes are the exception: each can have the name with its own value (SCRT-L0-08).",
"remedy": "Repeat the call with the scope that the refusal's scope, application, and environment members give, or store the value under a new name at the scope you want.",
"members": {
"scope": {
"type": "string",
"description": "The kind of scope the name is at: account or application."
},
"application": {
"type": [
"string",
"null"
],
"description": "The id of the application whose scope the name is at, null where it is at the account scope."
},
"environment": {
"type": [
"string",
"null"
],
"description": "The environment of that application scope, development or production, null where the name is at the account scope."
}
}
},
{
"name": "secret_count_limit",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "SEC-L0-21",
"summary": "store_secret would add a name to a scope that already has 100 counted names. At an environment scope of an application, every name stored there counts, the platform's own included. At the account scope, only the names you stored count. Nothing was written, no grant was minted, and a grant the call presented stays unspent.",
"remedy": "Delete a name no longer needed there with delete_secret, once nothing uses it, then store again. A re-supply or a rotation of a name that exists there is never refused."
},
{
"name": "secret_exists",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "SEC-L0-20",
"summary": "store_secret was called with generate for a name that already exists at that scope, whether its value was supplied or created. A call with generate never replaces a value, so nothing was written.",
"remedy": "To replace a created value, store a new name with generate, bind the setting to it, deploy, then delete the old name with delete_secret. To supply a value of your own under the existing name, call store_secret without generate."
},
{
"name": "secret_grant_expired",
"surfaces": [
"management_action"
],
"status": 403,
"owner": "MAPI-03",
"summary": "The secret grant passed its expiry before its one write was made, so nothing was written. The grant a `submit_manifest` call with `local_run` mints expires the same way: a `store_secret` with `replace: true` request under it after its expiry re-mints nothing.",
"remedy": "Call `store_secret` from your tool again with no value, and run the command it returns before the expiry it states. For the local run's line, run `turnzero provision --application <application id>` with nothing piped, adding `--origin` where your other lines include one, and make any call it prints.",
"members": {
"credential_kind": {
"type": "string",
"description": "The kind of the credential refused: secret_grant."
}
}
},
{
"name": "secret_grant_not_admitted",
"surfaces": [
"management_action",
"mcp_server",
"storage",
"egress",
"logging",
"documentation",
"realm_surface",
"push",
"email"
],
"status": null,
"owner": "MAPI-03",
"summary": "The secret grant a `store_secret` call with no value mints serves the one write it records: the same action on the HTTP action route, with the grant's own name, application, and environment. The grant a `submit_manifest` call with `local_run` mints serves two requests: `store_secret` with `replace: true` on that route, with no value, for the application's database credential and its platform credential at the development scope, each once. Under either grant, every other surface, management action, and request is refused with this name (403; a 401 challenge at the MCP server) and uses nothing. The exception is an action another rule refuses first. The browser-only action reads no credential, and an action that is switched off reads the grant and refuses with its switch's name; neither accepts the grant. A provision grant claimed by its verifier is no grant anywhere else. Every action but `store_secret` with `replace: true` over the wire, and every other surface, reads the verifier as a bearer that resolves to nothing, refused `authentication_required`. The deploy command's progress read refuses it under that read's own name, `transfer_grant_not_admitted`.",
"remedy": "Run the command the preparing call returned once, as given: it makes the one write the grant allows. For any other act, present the credential that surface accepts, for example a signed-in session or a minted token on the management surface. To write another name or at another scope, call `store_secret` with no value for that name and scope, and run the command it returns. For the local run's grant, run the line the `submit_manifest` call returned, as given. For a fresh one, run `turnzero provision --application <application id>` with nothing piped and make any call it prints.",
"members": {
"credential_kind": {
"type": "string",
"description": "The kind of the credential refused: secret_grant."
}
}
},
{
"name": "secret_grant_spent",
"surfaces": [
"management_action"
],
"status": 403,
"owner": "MAPI-03",
"summary": "The secret grant's one use was already taken. A grant serves one write, so a write under a spent grant is refused and writes nothing. The `list_secrets` action shows when the name was last written. Where the same line ran before and returned slowly, that earlier run took the use and may have written the value. Where the refused write is the command's first run, another holder of the grant took that use, and the value in custody may not be yours. The grant a `submit_manifest` call with `local_run` mints re-mints once each credential local runs use: the platform credential, and the database credential where the manifest declares the database. The platform credential's re-mint spends it, and a second re-mint of the database credential under it is refused by this name too. Where the refused line is the command's first run, another holder of the grant made that re-mint.",
"remedy": "Do not run the command again. Where `list_secrets` shows no write at the time the command first ran, or that first run was refused this way, call `store_secret` from your tool again with no value. Run the command it returns, which replaces the value under that name. For the local run's grant, run `turnzero provision --application <application id>` with nothing piped, adding `--origin` where your other lines include one, and make any call it prints. Its line re-mints the platform credential, and the database credential where the manifest declares the database, which ends the values an earlier re-mint returned.",
"members": {
"credential_kind": {
"type": "string",
"description": "The kind of the credential refused: secret_grant."
}
}
},
{
"name": "secret_in_use",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "SCRT-L0-07",
"summary": "delete_secret: something still reads the secret you gave, so its value may not end. For an application-scope name, a binding may feed it in the recorded manifest or in the serving row of the environment whose scope has it. A binding in a deploy, promote, or restart in flight to that environment also counts. Or an upstream declaration of the application uses it as its key. Or the realm or the push configuration of the environment whose scope has it uses it now as a route credential. A route of the other environment, and a value resting in the cell's realm vault after its realm came to use another name, are not uses, and the deletion ends that resting copy. An account-scope name is in use only where an upstream declaration of any of your account's applications uses it, since no binding and no realm or push route reads the account scope. The detail lists each use. The request is refused before any pending action, and a use made after the approval ends the pending action failed with this refusal. Nothing was removed.",
"remedy": "End each use the detail lists, then call delete_secret again. Remove a binding from the manifest's settings, call submit_manifest, and deploy or promote each environment whose running copy has the binding, once any act in flight with it has ended. Point an upstream, a realm route, or a push configuration at another stored name with declare_outbound_api, configure_app_sign_in, or configure_push, or end an upstream the application no longer calls with declare_outbound_api and remove true."
},
{
"name": "server_unavailable",
"surfaces": [
"management_action"
],
"status": 503,
"owner": "PLD-L0-131",
"summary": "submit_manifest, promote, or deploy to production: the database cannot be provisioned. No server of the application's hosting cell that accepts new databases has fewer databases than its bound while using under 70 percent of its storage. Or an earlier run of the provisioning recorded a server that no longer accepts new databases, so the run cannot move to another server until that earlier run is removed. On a promote or a production deploy, the history row ends failed with this outcome at its database_pair step.",
"remedy": "On submit_manifest, where the detail identifies an earlier run, repeat submit_manifest once, since that run may still be completing. If the refusal repeats, call delete_environment on development, which removes the run, on one environment or two, together with the secrets, files, and logs kept at the development scope. On two environments, create_environment follows it, and a resubmission then sets the database up again. Where the detail identifies no earlier run, or that deletion fails, report the refusal with its detail. Repeat submit_manifest once the platform's operator has added a database server to the cell, or has removed the earlier run or set its server to accept databases again. On a promote or a production deploy whose detail identifies an earlier run, report the refusal with its detail. The platform's operator removes that run or sets its server to accept databases again, and the next promote or deploy then goes through. Where it identifies none, repeat the act once a server accepts new databases."
},
{
"name": "serverless_no_websocket",
"surfaces": [
"router",
"management_action"
],
"status": 400,
"owner": "FNS-L0-06",
"summary": "A serverless application cannot keep a WebSocket connection open. The router refuses an upgrade and forwards nothing. Manifest submission and checking refuse `websockets`; the recorded manifest stays unchanged.",
"remedy": "Use HTTP requests. Remove `websockets` from a serverless application's manifest, or create a server application where a connection must stay open."
},
{
"name": "serverless_not_available",
"surfaces": [
"management_action"
],
"status": 403,
"owner": "FNS-L0-02",
"summary": "You requested serverless creation or a deploy or manifest call while that kind is not yet available. The call was refused before any write.",
"remedy": "For creation, pass kind server or omit it. For an existing serverless application, retry the deploy or manifest call when that kind is available."
},
{
"name": "serverless_static_only",
"surfaces": [
"management_action"
],
"status": 403,
"owner": "FNS-L0-02",
"summary": "A serverless application cannot use the requested function files, migrations, database or schedule services, egress hosts, size, sleep setting or plan. Nothing was recorded.",
"remedy": "For a deploy or manifest, remove the unsupported files or declarations and try again. If they are required, create a server application for that work. For a size, sleep setting or plan, create a server application."
},
{
"name": "session_credential_required",
"surfaces": [
"management_action"
],
"status": 403,
"owner": "MAPI-14",
"summary": "mint_token can be called only under a signed-in session credential: a minted token mints no token (MAPI-14).",
"remedy": "Under a minted token, you need no new token for the storage routes, the keyed upstreams, and the action routes within its scope: the token you presented already serves them. The logging routes and the platform upstream take a token bounded to an application, or its platform credential. If your tool is connected by a minted token, set TURNZERO_CLOUD_MINTED_TOKEN from where its token is kept, never by writing the value in a line, and TURNZERO_CLOUD_ORIGIN on another estate. Then run the turnzero command's deploy or check line, since mint_token takes a sign-in session alone. To replace a token nearing its expiry, mint another from the signed-in session."
},
{
"name": "session_ended",
"surfaces": [
"realm_surface"
],
"status": 401,
"owner": "ACS-L0-06",
"summary": "No session exists for the presented value, its user or realm no longer exists, or the session token fails verification under the realm's keys.",
"remedy": "Have the end user sign in again; a new sign-in opens a new session. Where your backend caches verdicts, keep this refusal for no more than ten seconds."
},
{
"name": "session_expired",
"surfaces": [
"realm_surface"
],
"status": 401,
"owner": "ACS-L0-06",
"summary": "The session is past its expiry.",
"remedy": "Have the end user sign in again; a new sign-in opens a new session. Where your backend caches verdicts, keep this refusal for no more than ten seconds."
},
{
"name": "session_other_account",
"surfaces": [
"realm_surface"
],
"status": 403,
"owner": "ACS-L0-06",
"summary": "On the verification route, the realm belongs to an account other than the credential's account.",
"remedy": "Verify with a credential of the account the realm's application belongs to: its account-wide credential or a token minted for that application, with the realm's environment in the request. The application's own platform credential also works."
},
{
"name": "session_other_realm",
"surfaces": [
"realm_surface"
],
"status": 403,
"owner": "ACS-L0-06",
"summary": "On the verification route, the session belongs to another realm: another application's realm, or the other environment's realm of the same application.",
"remedy": "Verify the session through the application environment whose realm has it: present that environment's platform credential, or, from a script of the owning account, give that environment in the request. Otherwise have the end user sign in to this application."
},
{
"name": "session_required",
"surfaces": [
"realm_surface"
],
"status": 401,
"owner": "ACS-L0-06",
"summary": "A route that needs an end-user session received none: no session cookie, and no session token as the bearer.",
"remedy": "Send the request with the end user's session cookie, which this application's sign-in set, or present that cookie's value as the bearer credential. An end user with no session signs in first."
},
{
"name": "session_revoked",
"surfaces": [
"realm_surface"
],
"status": 401,
"owner": "ACS-L0-06",
"summary": "The session was signed out, every session of the user ended, or, on the verification route, revoke_app_sign_in_keys revoked the realm key that signed the session token.",
"remedy": "Have the end user sign in again; a new sign-in opens a new session. Where your backend caches verdicts, keep this refusal for no more than ten seconds."
},
{
"name": "setting_is_upstream_key",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "MAN-14",
"summary": "submit_manifest, deploy, or promote: a `settings` entry binds a secret that an upstream declaration of the application gives as its key. The egress gateway applies that key at its edge and never gives it to the application, so no binding may use it (EGW-L0-03). Nothing was recorded or written.",
"remedy": "Call the upstream through the egress gateway instead of reading its key, or store the value the code reads under another name and bind that name. Then call submit_manifest again, and deploy or promote again where the refusal came from one."
},
{
"name": "setting_scope_refused",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "MAN-14",
"summary": "submit_manifest: a `settings` entry binds a secret that exists at the account scope or at another application's scope, where no deploy of this application reads it (SCRT-L0-08). A value stored at the account scope is applied only to a declared upstream's calls, and a name never moves between scopes; nothing was recorded.",
"remedy": "Store the value under a new name with store_secret, giving this application and each environment, bind that name in the manifest's settings, and call submit_manifest again."
},
{
"name": "setting_secret_missing",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "MAN-14",
"summary": "deploy or promote: a setting the manifest binds gives a secret that is not stored at the environment's scope of the application. The detail gives the setting and the secret, and nothing was written. The refusal's `next` member is the `store_secret` call for that application and environment, with no value (MAPI-24). A deploy or promote whose bound name lost its entry after it started ends its row failed with this refusal. A value whose entry exists but whose store does not respond is refused `bound_setting_unreadable` instead.",
"remedy": "Make the store_secret call in the refusal's `next`; its response gives the line that sends the value. A failed row has no `next`, so call store_secret for the application and that environment. Then deploy or promote again. Or remove the binding from the manifest's settings, call submit_manifest, and deploy or promote again.",
"members": {
"next": {
"type": "object",
"description": "The one call that remedies the refusal, the object alone (MAPI-24): store_secret for the application and the environment the act targets. It carries the secret's name and never a value, and its answer gives the line that sends the value.",
"properties": {
"action": {
"type": "string",
"description": "The action to call: store_secret."
},
"arguments": {
"type": "object",
"description": "The call's arguments, filled in whole: no value is among them.",
"properties": {
"name": {
"type": "string",
"description": "The secret's name, the one the setting binds."
},
"application": {
"type": "string",
"description": "The application's identifier."
},
"environment": {
"type": "string",
"description": "The environment the deploy or promote targets, development or production."
}
}
}
}
}
}
},
{
"name": "setup_mail_production_only",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "ACS-L0-23",
"summary": "A setup-email send or resend was requested on the development estate. The email links production's origin, so production alone sends it; nothing was sent and no first-send claim or resend attempt was written.",
"remedy": "Request the email from the production estate."
},
{
"name": "sign_in_failed",
"surfaces": [
"builder_sign_in"
],
"status": 400,
"owner": "MCP-02",
"summary": "The provider sign-in could not be verified.",
"remedy": "Start the sign-in again from your tool."
},
{
"name": "sign_in_required",
"surfaces": [
"builder_sign_in"
],
"status": 401,
"owner": "MCP-02",
"summary": "No provider sign-in is configured for the authorization, or a passkey management route was reached without a signed-in browser session. Or a sign-in whose code goes to a host other than a loopback address completed on a server keeping no browser sign-in, which cannot show the page that asks to allow the tool; nothing minted.",
"remedy": "For a passkey route, sign in again in the browser, then return to the passkey page. Where no provider sign-in is configured on the server, or the server keeps no browser sign-in, nothing you do corrects this until the platform configures one."
},
{
"name": "signin_code_invalid",
"surfaces": [
"management_action",
"realm_surface",
"builder_sign_in"
],
"status": 400,
"owner": "ACS-L0-12",
"summary": "The sign-in code is wrong, expired, superseded, or unbound, and the refusal does not say which. The attempt is spent, and the sixth attempt ends the code. The `sign_in_test_end_user` action returns it on its command route where the stored code did not confirm, or no code was stored, and nothing is signed in.",
"remedy": "Enter the code again from the browser that asked for it. If the code has expired or its attempts are spent, start the sign-in again from that browser to receive a new code."
},
{
"name": "signin_code_rate_limited",
"surfaces": [
"management_action",
"realm_surface",
"builder_sign_in"
],
"status": 429,
"owner": "ACS-L0-12",
"summary": "An emailed-code sign-in start went past the per-address send rate, the address's failure count for the hour, or the per-realm or estate-wide send ceiling. The start that `sign_in_test_end_user` makes on its command route is refused the same way where the test end user's address reached the per-address rate, and nothing is signed in.",
"remedy": "Wait for the hour to pass, then start the sign-in again, because requesting another code sooner does not reset the count. On an end-user realm, if you are the application's author, you can raise the per-address send rate with configure_app_sign_in."
},
{
"name": "signin_rate_limited",
"surfaces": [
"management_action",
"realm_surface",
"builder_sign_in"
],
"status": 429,
"owner": "ACS-L0-07",
"summary": "A sign-in start went past a per-source rate. The rate is an end-user realm's for its provider and emailed-code starts, or the builder realm's per-source window on emailed-code starts. Or it is one network source's share of emailed-code starts an hour across every realm. That share is a sixth of the estate-wide ceiling as computed from the estate's sender quota, and the detail gives its number (ACS-L0-12). The start that `sign_in_test_end_user`'s command route, or the `test_end_user` of `request_route` or `write_route`, makes counts in the end-user realm's rate under the caller's source address, beside the browser's starts, and is refused the same way past it (ACS-L0-21; MAPI-28).",
"remedy": "Wait until the hour's window passes, or start the sign-in from another network. On an application's realm, if you are the application's author, raise the per-source rate with configure_app_sign_in (limits.signin_starts_per_hour). The builder realm's rate is fixed. One network source's share of emailed-code starts an hour, across every realm, is a sixth of the estate-wide ceiling, and nothing you do raises it. The refusal's detail gives the number."
},
{
"name": "slot_busy",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "PLD-L0-63",
"summary": "deploy, promote, or restart: the environment's previous compute could not be torn down after the routers' interval, or the candidate's compute slot still existed when the wait for its absence ended. Nothing was applied, and the history row ends failed with this outcome.",
"remedy": "Deploy or promote again; the retry runs the teardown and the wait again and deletes what remains under the slot. Where it repeats, read the environment's state through read_status and the platform events through read_logs."
},
{
"name": "slow_down",
"surfaces": [
"builder_sign_in"
],
"status": 400,
"owner": "MCP-02",
"summary": "Your program polled the token endpoint under the device-code grant sooner than the interval allows after its last poll (RFC 8628). The request is still pending and no token is issued.",
"remedy": "Poll at most once every five seconds."
},
{
"name": "smoke_path_failed",
"surfaces": [
"management_action"
],
"status": 502,
"owner": "PLD-L0-59",
"summary": "deploy or promote: after the health gate passed, a path the manifest's smoke_paths lists kept returning 404, a status of 500 or above, or nothing until 30 seconds had passed. The candidate is deleted, and the serving compute is untouched. The history row ends failed with a smoke member: the path, its response, the candidate's state, and the console's last lines.",
"remedy": "Read the failed row's smoke member through read_status: its console shows the crash. Fix the route or what it calls, such as a missing upstream key, and deploy again, or remove the path from smoke_paths with submit_manifest. A serving version, where one serves, is unchanged."
},
{
"name": "socket_limit_reached",
"surfaces": [
"router"
],
"status": 429,
"owner": "SVC-L0-23",
"summary": "The serving router replica has reached one of its counts of upgraded connections, or is within its margin of its open-file limit (SVC-L0-23). The detail gives the bound reached. On a pod-grain leg, the cell's front refuses an upgrade past its own bound with a marked response. The router refuses with this name on that mark, its detail citing the front's bound or the environment's share of it. A stopping replica refuses with it too, with `Retry-After: 1`. Nothing was forwarded to the application.",
"remedy": "Close a connection before opening another, or retry with a growing wait. Where the detail reports a stopping replica, open the connection again, and another replica takes it. Where the environment's own connections-per-replica bound is reached, move a shared-0.5gb application to shared-1gb with set_app_size only at the account owner's request. Ask for a size they have not chosen; if nobody can answer, report the refusal and change no size. The move changes production to the larger size's rate key. Without a recorded sleep setting, it stays awake for the whole month."
},
{
"name": "space_creation_ceiling",
"surfaces": [
"management_action"
],
"status": 403,
"owner": "MAPI-18",
"summary": "Creating the space would exceed your account's space limit, and nothing was created. Every account has a limit of five spaces. A repeat that gives a space your account already owns returns that space as it is, whatever the count.",
"remedy": "Use a space your account already owns, or delete one you no longer need with delete_space, which a person approves in the browser, then create the new space. The limit itself is the platform's."
},
{
"name": "space_not_owned",
"surfaces": [
"management_action"
],
"status": 403,
"owner": "MAPI-14",
"summary": "The request gave a space your account does not have, or cannot use as given, and nothing was recorded or created. For mint_token, it is a space the issues grant would include that your account does not have. Or it is one space of an application's per-environment pair, whose tokens the platform keeps per environment and not in its vault. For relay_issue_act, from an account holding the profile the relay needs, it is a space your account neither has nor is a member of, whatever the credential, or one other than the space its token's grant is for. For share_space, from an account holding the profile it needs, it is a space your account does not have; a member of a shared space cannot share it.\n\nFor delete_space, it is a space your account does not own: one shared with it, at any level, or an identifier no space of yours uses; only the account that owns a space deletes it. For rename_space, it is a space your account does not own, in the same way; only the account that owns a space renames it. For create_space, from an account holding the profile it needs, it is an identifier another owner's space already uses. For submit_manifest, it is an issue_tracking entry that gives a space your account does not have, or an application's own space, this application's or another's, which binds only through its own manifest. The platform's own space belongs to the one account the platform sets as its owner.",
"remedy": "Pass a space that list_issue_spaces returns for your account, or an application's own space as submit_manifest's receipt gives it, or create one with create_space. To reach another account's space, mint a token for it from a signed-in session of the account that has it. Work a space of an application's per-environment pair through the feedback actions, giving `space`. For a manifest, leave `space` out so the application gets a space of its own, or pass a space of your account's own.",
"members": {
"space": {
"type": "string",
"description": "The space the request gave."
}
}
},
{
"name": "standing_stale",
"surfaces": [
"router"
],
"status": 503,
"owner": "SVC-L0-07",
"summary": "The serving router refuses with this on every path of the application's hostname, the shell and the reserved prefix included. The operator has set how long a router may keep serving from the control plane's last response (`ROUTER_STANDING_MAX_AGE_S`, no limit by default). The control plane has not responded to that router replica for longer than that. So the router cannot tell whether the owning account is still in good standing, and serves nothing from its saved copy. With no limit set, the router serves from its saved copy through any outage and never refuses with this, and a recorded suspension or halt keeps its own refusal.",
"remedy": "Nothing you do corrects this. The refusal ends when the control plane responds to the router again; the platform operator restores the control plane, and the platform status reports the outage. An end user retries once the application responds again."
},
{
"name": "status_setting_unknown",
"surfaces": [
"management_action"
],
"status": 400,
"owner": "PLD-L0-76",
"summary": "You gave a setting the status record does not serve. Nothing was written. The status record serves these twenty-six settings: probe_hostname, probe_path, samples_to_open, samples_to_close, probe_timeout_ms, stale_minutes, certificate_floor_days, error_counter_per_day, schedule_platform_outcomes_per_hour, mark_redeploy_concurrency, console_live_tail, unlimited_allowance_daily_signal_usd_micros, token_code_seconds, custom_domains, invite_only_products, tzmesh_front, tztrack_front, tztrack_billing, pricing_model, serverless_kind, image_undelivered_per_hour, credit_sales, account_picture, dedicated-database-sizes, ai_default_model, and ai_default_thinking_level.",
"remedy": "Use one of the names listed in the summary. If the value breaks that setting's limits, the refusal is `invalid_request` and its detail gives the limits."
},
{
"name": "storage_error",
"surfaces": [
"storage"
],
"status": 500,
"owner": "PLD-L0-80",
"summary": "A storage route failed unexpectedly. The platform records the failure under a reference that the detail gives, and the detail never includes the error's own message.",
"remedy": "Retry the request. If the refusal repeats, report it and quote the reference its detail gives."
},
{
"name": "store_unavailable",
"surfaces": [
"management_action",
"realm_surface",
"builder_sign_in",
"storage",
"egress",
"logging",
"push",
"email",
"deploy_progress",
"workflow_start",
"account_mail"
],
"status": 503,
"owner": "PLD-L0-67",
"summary": "The plane's database did not respond to the credential lookup the guard runs, so the request was not processed; retry it. On the storage, egress, and logging wires, the same refusal comes where the gateway had no entry within its stale ceiling. On submit_manifest, the control store failed while the manifest's upstreams were written after its record. A write the failure followed is taken back where it can be, the manifest stays recorded, and the detail lists the upstreams declared, those not, and any left over. A failure while the realm member or the push entry's providers are recorded, after the upstreams, takes nothing back. What was recorded remains, and the detail lists the realms, or the push configurations, done and those not. On the start-line route, the line was not stored, and the workflow posts it again.",
"remedy": "Repeat the same request unchanged, since it was not processed and a repeat causes no duplicate effect. If the refusal continues, wait a short time and repeat the request again. On submit_manifest, the request was processed in part, and submitting the same manifest again before the next deploy or promote completes the declarations. Submitting it again also completes the realms and the push configurations."
},
{
"name": "subject_is_caller",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "API-L0-12",
"summary": "A staff suspension was given the calling credential's own account. A suspension ends its sessions, revokes its exchange tokens, refuses its other credentials until reinstatement, and stops its serving. Suspending your own account would end the session you would call its reinstatement under. The standing is not written, and the serving walk does not run.",
"remedy": "Pass the account you mean to suspend. To stop your own account's service, ask another operator account to suspend it."
},
{
"name": "subject_missing",
"surfaces": [
"realm_surface"
],
"status": 403,
"owner": "ACS-L0-09",
"summary": "The work-account or Sign in with Apple id_token has no subject.",
"remedy": "Nothing in the realm's settings corrects this. On the work-account route, ask the client's tenant administrator to check the app registration that issues the token. On either route, ask the end user to sign in again."
},
{
"name": "support_read_rate_capped",
"surfaces": [
"support_read"
],
"status": 429,
"owner": "MAPI-29",
"summary": "A support read token read the shared account more than 30 times in this minute, or the chat 600 times in the last 60 minutes across its tokens. The read was not made, it did not count against the chat's hour, and the refusal is recorded under the token.",
"remedy": "Wait the seconds in Retry-After, the time to the next minute or until enough of the chat's reads leave the last 60 minutes, then read again."
},
{
"name": "support_unavailable",
"surfaces": [
"support_read"
],
"status": 503,
"owner": "MAPI-29",
"summary": "Sharing an account with support is not set up on this site: no support bridge is configured, or the site holds no browser credential secret. Nothing is minted. A wider read is refused with this name where the site reads no deployed files or holds no dispatcher seam.",
"remedy": "Ask your question without sharing the account, or try again later."
},
{
"name": "support_unreachable",
"surfaces": [
"support_read"
],
"status": 502,
"owner": "MAPI-29",
"summary": "The support agent did not take the shared access within 5 seconds, so the token minted for it was revoked at once and nothing is shared.",
"remedy": "Wait a minute, then click to share again."
},
{
"name": "synthetic_account_fixed",
"surfaces": [
"management_action",
"builder_sign_in"
],
"status": 403,
"owner": "ACB-L0-79",
"summary": "An identity or a passkey tried to join a synthetic account and was refused. A synthetic account has exactly the identities its seed bound and signs in through the emailed-code route alone; an access-link account signs in through its link alone. The refusing sites are link_identity, the link ticket, the add-a-route start and its callback, the same-address interrupt ahead of its choice and its code and link exits, and the passkey registration routes.",
"remedy": "Nothing corrects this: a synthetic account gains no identity and no passkey. Sign in on the emailed-code route with the fixture address the seed bound, its code read through the staff read of a synthetic sign-in code. An access-link account signs in by its link alone."
},
{
"name": "synthetic_ceiling_reached",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "MAPI-16",
"summary": "A count that the synthetic-account mode, or the synthetic_seed_purge grant, bounds is reached. At a seed, the count is the existing synthetic accounts, or the accounts this operator's account seeded in the current UTC day. At create_application or set_app_size for a synthetic-owned application, it is the existing synthetic applications, or those whose stored plan is not Free. Under the synthetic_seed_purge grant, a seed also meets that grant's own ceiling: sixteen existing synthetic accounts that the calling credential seeded. An account seeded under that grant can hold one application at shared-0.5gb. A second application, or creating or moving one to shared-1gb, is refused. The ceiling paid_applications_per_account refuses the larger size and counts applications whose stored plan is not Free. The refusal gives the ceiling and its value.",
"remedy": "Purge the synthetic accounts you no longer need, or wait for the lifetime sweep or the next UTC day. A ceiling is a constant of the mode or of the grant, and no call raises it. For paid_applications_per_account, create the application at shared-0.5gb, or leave it at that size.",
"members": {
"ceiling": {
"type": "string",
"description": "The name of the ceiling reached: standing_accounts, seeded_per_day, standing_applications, paid_applications, or, under the synthetic_seed_purge grant, standing_accounts_per_credential. For an account seeded under that grant, paid_applications_per_account is the ceiling on its applications whose stored plan is not Free. Under usage, applications_per_account is the ceiling on all applications an account seeded under that grant holds."
},
"value": {
"type": "integer",
"description": "The ceiling's constant, under the mode read or, for standing_accounts_per_credential and paid_applications_per_account, under the synthetic_seed_purge grant. For applications_per_account it is the allowed application count."
},
"standing": {
"type": "integer",
"description": "The count measured against the ceiling before the call. For seeded_per_day it is the accounts this operator's account seeded in the current UTC day. For standing_accounts_per_credential it is the existing synthetic accounts the calling credential seeded. For paid_applications_per_account it counts the account's applications whose stored plan is not Free, excluding the one being moved. For applications_per_account it counts all applications the seeded account holds."
}
}
},
{
"name": "synthetic_estate_bounded",
"surfaces": [
"management_action"
],
"status": 403,
"owner": "MAPI-16",
"summary": "You called an action outside the bound of a minted token that has the synthetic_estate grant and no super_admin. The grant limits its token to the actions it marks and to the actions whose `admits` mark lists it, list_tokens and submit_feedback. The actions marked access: anonymous are outside the bound and serve the token as they serve every connection.",
"remedy": "Call the action from the owner's signed-in session, or under a token minted through mint_token without the synthetic_estate grant. The refusal's `admitted` member lists the actions the bounded token can reach.",
"members": {
"grant": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]*$",
"description": "The grant that bounds the credential presented."
},
"admitted": {
"type": "array",
"items": {
"type": "string"
},
"description": "The actions the bound admits, in the enumeration's order: the rows the grant marks and the rows whose admits mark lists it. The rows marked access: anonymous lie outside the bound and are not listed."
}
}
},
{
"name": "synthetic_estate_disabled",
"surfaces": [
"management_action"
],
"status": 403,
"owner": "MAPI-16",
"summary": "A write of the synthetic estate, a seed or a purge, arrived while the control plane's SYNTHETIC_ESTATE mode reads off, and was refused ahead of every other check. While the mode is off, the two actions are not listed as tools. The reads remain available: a purge's progress, a sign-in code, and the reads of existing synthetic accounts. The platform's own lifetime sweep purges expired batches regardless. A stranded estate is purged after the mode is set.",
"remedy": "Nothing you call sets the mode, so ask the platform's operator to set it to compat or stress, then repeat the request. Meanwhile the reads of a purge's progress, a sign-in code, and existing synthetic accounts still work."
},
{
"name": "synthetic_posture_refuses",
"surfaces": [
"management_action"
],
"status": 403,
"owner": "MAPI-16",
"summary": "An act that the synthetic-account mode in force, or your bounding grant, does not allow. The cases are a seed whose count is past the mode's per-call bound, or whose token_expires_in_days is past the mode's expiry bound. They also include all: true on the purge outside the stress mode, or from a credential a synthetic grant bounds. Under the synthetic_seed_purge grant, a seed of more than one account, a seed whose token lives past one day, or a seed that passes products, tools_plan, or app_hosting. The refusal gives the bound.",
"remedy": "Repeat within the mode's bounds — a smaller count, a shorter token_expires_in_days, explicit accounts in place of all — or ask the platform's operator to set the stress mode. Under the synthetic_seed_purge grant, seed one account for one day and leave products, tools_plan, and app_hosting out: no mode widens that grant's bounds.",
"members": {
"bound": {
"type": "string",
"description": "The name of the bound that refused: accounts_per_seed, token_expiry_days, products, tools_plan, or app_hosting on a seed, all on a purge."
},
"value": {
"type": "integer",
"description": "The bound's constant, under the effective mode or under your bounding grant, present on a seed's refusal that gives accounts_per_seed or token_expiry_days."
},
"posture": {
"type": "string",
"description": "The mode the refused act met: the effective seed mode on a seed, the mode as set on a purge."
},
"grant": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]*$",
"description": "The bounding grant your credential holds without super_admin, present only where the grant is why the act was refused: all on a purge, or a seed past the grant's own bounds."
}
}
},
{
"name": "synthetic_seed_purge_bounded",
"surfaces": [
"management_action"
],
"status": 403,
"owner": "MAPI-16",
"summary": "You called an action outside the bound of a minted token that has the synthetic_seed_purge grant and no super_admin. The grant limits its token to seeding and purging synthetic accounts and reading a purge, the three actions whose `admits` mark lists it. The actions marked access: anonymous are outside the bound and serve the token as they serve every connection. An action another grant marks refuses with grant_required first.",
"remedy": "Call the action from the owner's signed-in session, or under a token minted through mint_token without the synthetic_seed_purge grant. The refusal's `admitted` member lists the actions the bounded token can reach.",
"members": {
"grant": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]*$",
"description": "The grant that bounds the credential presented."
},
"admitted": {
"type": "array",
"items": {
"type": "string"
},
"description": "The actions the bound admits, in the enumeration's order: the rows the grant marks and the rows whose admits mark lists it. The rows marked access: anonymous lie outside the bound and are not listed."
}
}
},
{
"name": "target_environment_halted",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "PLD-L0-41",
"summary": "promote, roll_back, run_schedule, deploy, restart_application, and a change of size or sleep setting by set_app_size, or the operator's placement, that changes production's group or grain: the environment the act targets is halted. Call `halt_environment` with `resume: true` to end the halt, and then the act can run. A deploy to halted production is refused; a deploy to halted development ends the halt itself, whereas restart_application never ends either environment's halt (PLD-L0-41).",
"remedy": "Call halt_environment with resume: true for the application and environment, then repeat the promote, roll_back, run_schedule, deploy, or restart_application. A deploy to halted development needs no resume, because the deploy itself ends the halt."
},
{
"name": "temporarily_unavailable",
"surfaces": [
"builder_sign_in"
],
"status": 503,
"owner": "MCP-02",
"summary": "The device authorization request could not draw a user code that no live request already uses, after three tries (RFC 8628). Nothing was written.",
"remedy": "Send the device authorization request again."
},
{
"name": "tenant_mismatch",
"surfaces": [
"realm_surface"
],
"status": 403,
"owner": "ACS-L0-09",
"summary": "The work-account id_token has an Entra tenant other than the configured one.",
"remedy": "Ask the end user to sign in with an account of the configured tenant. If the wrong tenant is configured, correct entra.tenant with configure_app_sign_in, then ask the end user to sign in again."
},
{
"name": "test_end_user_fixed",
"surfaces": [
"realm_surface"
],
"status": 403,
"owner": "ACS-L0-20",
"summary": "An identity or a passkey would join a test end user. A test end user has exactly the one fixture-domain email identity its creation bound, and signs in only through the emailed-code route. Linking a sign-in route, the same-address prompt, and passkey registration each refuse with this.",
"remedy": "Nothing corrects this: a test end user gains no identity and no passkey. Sign it in on the emailed-code route with its fixture address, reading the code with read_test_signin_code."
},
{
"name": "test_end_user_sign_in_unavailable",
"surfaces": [
"management_action"
],
"status": 503,
"owner": "ACS-L0-21",
"summary": "request_route or write_route with test_end_user, or the command route of sign_in_test_end_user, which the turnzero session line calls, reached a platform service that cannot sign a test end user in. Nobody was signed in and nothing was requested.",
"remedy": "Sign the test end user in at the realm's sign-in page with its fixture address, reading the code with read_test_signin_code, as step 3 or step 5 of read_documentation's page /guides/test-sign-in-with-test-end-users/ does, then send requests with that session."
},
{
"name": "test_end_users_ceiling_reached",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "ACS-L0-21",
"summary": "add_test_end_users with labels would pass one of its bounds: twenty unexpired test end users existing on the realm, or fifty test end users created by the application's realms within the hour. Nothing is created, and the detail gives the bound.",
"remedy": "Remove test end users you no longer need with add_test_end_users and remove: true, pass fewer labels, or wait for the hour to pass. The bounds are constants, and no call raises them."
},
{
"name": "test_end_users_disabled",
"surfaces": [
"management_action"
],
"status": 403,
"owner": "ACS-L0-21",
"summary": "add_test_end_users with labels, sign_in_test_end_user, or request_route or write_route with test_end_user was called while the control plane's TEST_END_USERS setting reads off. While it reads off, no test end user's code is kept, and the realm's test sign-in page is refused with not_found. The read_test_signin_code action and add_test_end_users with remove: true still work, so you can remove test end users.",
"remedy": "Nothing you call turns the setting on: ask the platform's operator to turn it on, then repeat the request. Meanwhile, remove the test end users you no longer need with add_test_end_users and remove: true."
},
{
"name": "test_end_users_not_admitted",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "ACS-L0-21",
"summary": "A minted token without the `test_end_users` grant called add_test_end_users, read_test_signin_code, `sign_in_test_end_user` (for its line or on its command route), or request_route or write_route with `test_end_user`. It called on a production realm, or on a workforce application's realm. The account's session and a token carrying the grant are accepted on every realm. The detail gives the credential it read and the remedy.",
"remedy": "Mint a token with the `test_end_users` grant with mint_token, which the person claims with token claim, and call under it. Or call under the account's session: an MCP connection signed in through the browser, not one set up with a minted token, which presents that token. Adding a development environment is no remedy: it lasts, and every later deploy goes through it."
},
{
"name": "test_sign_in_unmarked",
"surfaces": [
"realm_surface"
],
"status": 404,
"owner": "ACS-L0-21",
"summary": "The accounts service's two test sign-in routes serve only the management service's own marked call from inside the plane. This request carried no mark or a wrong one, or came through the edge.",
"remedy": "Nothing you send marks the request. Sign a test end user in with sign_in_test_end_user, or name it in request_route's test_end_user, and the platform signs it in for you."
},
{
"name": "token_code_refused",
"surfaces": [
"management_action"
],
"status": 403,
"owner": "MAPI-23",
"summary": "mint_token's exchange on the HTTP action route under a token code, the one-time code a mint puts in its line, is refused. The code is unknown, expired, or already presented, by an earlier run of the line or by another party. Or its verifier does not match, the body has more than `code_verifier`, the account is suspended, or the session that minted it has ended. One refusal, alike in name, status, and detail, covers every such state, so it says nothing of whether a code existed. Every presentation there that the platform finds spends the code. The held form is the exchange under the verifier with the mint's id in the body. There a body with more than `mint`, an id outside its form, an unknown, ended, or expired row, or a challenge the verifier does not match is the same refusal with nothing spent. A match spends the row, so a suspended account or an ended session read after it leaves the row spent.",
"remedy": "Call `mint_token` again with the challenge the turnzero command printed, and run the line it returns once, as given."
},
{
"name": "token_exchange_failed",
"surfaces": [
"realm_surface"
],
"status": 403,
"owner": "ACS-L0-09",
"summary": "On the work-account or the Apple route, the provider's token endpoint refused the exchange, returned no id_token, or did not respond within the platform's round-trip bound.",
"remedy": "On the work-account route, store the app registration's current client secret again with store_secret, giving this application and the realm's environment, under the configured name. Correct entra.client_id with configure_app_sign_in where read_app_sign_in shows it differs from the registration's client id. On the Apple route, store the signing key again under apple.key_secret_name, and check the Services ID, team, and key identifiers. Then ask the end user to sign in again. If the refusal repeats at once, the provider is not responding; try again later."
},
{
"name": "token_scope_refused",
"surfaces": [
"management_action",
"realm_surface"
],
"status": 403,
"owner": "API-L0-17",
"summary": "An application-bounded minted token was used on a subject of another application. The same refusal applies to such a token on the application-less builder-realm form of invitation, list_invitations, or configure_app_sign_in (MAPI-09). It also applies on every form of the four feedback actions, which take no application, and on declare_storage_area with remove true for an area outside its reach (OST-L0-03). On declare_outbound_api with remove true, it refuses every application-bounded token, since only the account's own credential ends an upstream (API-L0-17).",
"remedy": "Address the request to the token's own application, or use a credential that reaches the other application: an account-wide session, or a token bounded to that application or to the account. A wider reach is a second token, minted from a signed-in session through mint_token, never an edit to the token you have.",
"members": {
"scope": {
"type": "object",
"description": "The bound of the token presented: the one application it reaches, outside which the request's subject lies.",
"properties": {
"kind": {
"type": "string",
"description": "The kind of bound, always application here."
},
"application": {
"type": [
"string",
"null"
],
"description": "The id of the application the token is bounded to, null where the credential is bounded to no application."
}
}
}
}
},
{
"name": "transfer_grant_expired",
"surfaces": [
"management_action",
"storage"
],
"status": 403,
"owner": "OST-L0-08",
"summary": "The transfer grant passed its expiry, and its minter must mint another. A deploy upload's grant allows its start only before its expiry.",
"remedy": "Mint a new grant for the same area, file, and direction: the application backend on the mint route, or mint_upload_grant for an upload. For an export's download, call request_export with download: true again and run the line it returns, which skips the files already on disk. Repeat the file act under the new grant before its expiry. For a deploy upload, call `deploy_command` with the application, naming no environment, and run the line it returns at once. The mint_upload_grant action and the mint route refuse the deploy area. Where read_status shows this upload as the `pending_upload` of the environment the deploy goes to, with a `retry`, make that call from your tool instead."
},
{
"name": "transfer_grant_not_admitted",
"surfaces": [
"management_action",
"mcp_server",
"storage",
"egress",
"realm_surface",
"push",
"email",
"deploy_progress"
],
"status": null,
"owner": "OST-L0-08",
"summary": "The transfer grant object storage mints serves its one file act and is refused by name everywhere else (403; a 401 challenge at the MCP server). An export's download grant serves only `GET` of a file by its name: its export's own files, and its application's stored files created by the time its export listed them. A stored file created later is refused with `no_such_file` under it, as an absent name is, and not with this refusal. A deploy upload's grant also serves its upload's one start on `deploy`, giving its own application, the environment its preparing call recorded, and upload. After that start, it serves the deploy command's progress reads of its own deploy inside their window, and the progress read refuses by this name every other credential and that grant before its start.",
"remedy": "Present the grant only on the one file route it covers, PUT or GET /storage/v0/areas/{area}/files/{name}, in the direction it was minted for. Under an export's download grant, read a file by its name, never a listing, the deploy area, or another application's area. Where a stored file the export's manifest lists is refused by this name, call `request_export` with `download: true` again and run the line it returns. For any other act, present the credential that surface accepts, for example a signed-in session or a minted token on the management surface. A deploy upload's grant starts only its own upload and then reads only that deploy's progress, as the turnzero command does under the grant its preparing `deploy` call returns. To read a deploy under your own credential, call `read_status`.",
"members": {
"credential_kind": {
"type": "string",
"description": "The kind of the credential refused: transfer_grant on the storage surface, the actions, and every other surface, and on the deploy command's progress read any kind presented."
}
}
},
{
"name": "transfer_grant_spent",
"surfaces": [
"management_action",
"storage"
],
"status": 403,
"owner": "OST-L0-08",
"summary": "The upload grant was spent by a write that landed, or, rarely, by a refused write whose hand-back of the spend failed, which wrote nothing. An upload grant serves one write (OST-L0-08). A deploy upload's grant is also spent by a later preparing call of `deploy` for the application, which replaces the upload. Its one start on `deploy` spends it too, a start the platform refused included. A deploy upload's grant returns 200 for its zip sent again after its write landed, writing nothing, until it expires and unless a later deploy call replaced the upload, and refuses other bytes.",
"remedy": "Under any grant but a deploy upload's, do not resend the write that spent it. For a further write to the file, mint a new upload grant, on the mint route or through mint_upload_grant, then send that write under it. For a deploy upload a later preparing `deploy` call replaced, call deploy_command with the application, naming no environment. Run the command it answers once, as given, from the application's folder, or `command_windows` on Windows; it deploys and prints its progress, then read read_status. Where these bytes were not written and, once the first run has ended, read_status shows neither this upload pending nor its deploy, the first write never landed. For a new deploy, make the same call and run its line: mint_upload_grant and the mint route refuse the deploy area. Where read_status shows this upload as the `pending_upload` of the environment the deploy goes to, with a `retry`, make that call from your tool to start it."
},
{
"name": "tzmesh_bounded",
"surfaces": [
"management_action"
],
"status": 403,
"owner": "MAPI-16",
"summary": "The call is outside the `tzmesh` grant's bound on this token. The token can call the actions the grant allows. It can also call `list_tokens` to read its own token, `submit_feedback` to file a report, and anonymous actions. It can call no other action of the account. The refusal gives the grant and the allowed actions.",
"remedy": "Make this call from the owner's signed-in session, or with a token minted without the `tzmesh` grant.",
"members": {
"grant": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]*$",
"description": "The grant that bounds the credential, tzmesh."
},
"admitted": {
"type": "array",
"items": {
"type": "string"
},
"description": "The rows the bound admits on this plane, the grant's own rows and those whose admits mark lists it."
}
}
},
{
"name": "tzmesh_required",
"surfaces": [
"management_action"
],
"status": 403,
"owner": "MAPI-14",
"summary": "`mint_token` requested the `tzmesh` grant for an account without tzMesh. Nothing was minted. The token code's exchange gives this refusal too if the account no longer has tzMesh. While `invite_only_products` lists `tzmesh`, the invite group's members and operator accounts have tzMesh (ACB-L0-76; ACB-L0-82).",
"remedy": "Your account must have tzMesh before you can make this request. Call `read_account` to see your account's products. While `invite_only_products` lists `tzmesh`, tzMesh comes with a tzTeam invitation. Once `tzmesh` leaves that list, every account has it."
},
{
"name": "tztrack_bounded",
"surfaces": [
"management_action"
],
"status": 403,
"owner": "MAPI-16",
"summary": "The call is outside the `tztrack` grant's bound on this token. The token can call the actions the grant allows, `list_tokens` to read its own token, `list_issue_spaces`, `submit_feedback`, and anonymous actions. It can call no other action of the account. A token issued by a sign-in's exchange can also call `share_space`, `list_space_members`, `create_space`, `rename_space`, and `delete_space`. A token minted with `mint_token` cannot call those five actions. The refusal gives the grant and the allowed actions.",
"remedy": "Make this call from the owner's signed-in session, or with a token minted without the `tztrack` grant.",
"members": {
"grant": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]*$",
"description": "The grant that bounds the credential, tztrack."
},
"admitted": {
"type": "array",
"items": {
"type": "string"
},
"description": "The rows the bound admits on this plane, the grant's own rows and those whose admits mark lists it."
}
}
},
{
"name": "undeclared_area",
"surfaces": [
"management_action",
"storage"
],
"status": 404,
"owner": "OST-L0-01",
"summary": "No area by that name is declared for your account, on a file route, the grant mint route, or mint_upload_grant. Declare it with PUT /storage/v0/areas/{area} or declare_storage_area, or list it under areas in the manifest's object_storage entry. `list_storage_files` and `read_storage_file` also refuse an undeclared area.",
"remedy": "Declare the area first with declare_storage_area or PUT /storage/v0/areas/{area}, or list it under areas in the manifest's object_storage entry and submit the manifest, then repeat the file request or the mint. Check the name against list_storage_areas, which lists the areas the account has declared. A name beginning `export-` or `deploy-` is the platform's and is never declared: choose another name."
},
{
"name": "undeclared_upstream",
"surfaces": [
"egress"
],
"status": 404,
"owner": "EGW-L0-01",
"summary": "No upstream with that name is declared for your account. Declare it with declare_outbound_api.",
"remedy": "Check the name against list_outbound_apis, and declare the upstream with declare_outbound_api where it is missing. Then send the call again."
},
{
"name": "unknown_action",
"surfaces": [
"management_action",
"mcp_server"
],
"status": 404,
"owner": "MAPI-10",
"summary": "No action by that name in the contract version, or none at this address. Where another address serves the name or its successor, the detail and the address member give it.",
"remedy": "Check the action name against the Management actions reference page, then repeat the request with a listed name. Where the detail gives a successor, call that action, with the mode the detail states for a merged action. Where the refusal carries address, send the call there. The documentation's page manifest, docs.json, records the contract version its pages describe.",
"members": {
"address": {
"type": "string",
"description": "The address that serves this action or its successor, where this address does not."
}
}
},
{
"name": "unknown_application",
"surfaces": [
"router"
],
"status": 404,
"owner": "SVC-L0-07",
"summary": "No live application has the label, or the application's owner record is missing.",
"remedy": "Send the request to the application's current hostname, which list_applications returns to its author, and allow the router's bounded interval after a rename. A deleted application's hostname never serves requests again, and where the owning account is being deleted nothing on your side corrects this."
},
{
"name": "unknown_environment",
"surfaces": [
"management_action"
],
"status": 400,
"owner": "PLD-L0-40",
"summary": "deploy on the HTTP API: the environment given is neither development nor production, the platform’s two. Over MCP, the argument’s own validation refuses such a value before the call.",
"remedy": "Pass `development` or `production`, or pass none: the deploy then goes to production on an application with one environment and to development on one with two. With two, a version reaches production through promote."
},
{
"name": "unknown_host",
"surfaces": [
"router"
],
"status": 404,
"owner": "SVC-L0-07",
"summary": "The Host line is not under the serving suffix, and the request does not have the apps edge's identifier. Or it has the identifier for a host that no custom-domain row with a route association has, or the plane has no apps-edge identifier (SVC-L0-25). On the serving router's invoke endpoint, the Host line is a label under the suffix, or the request came through the edge. That endpoint serves requests only on the router's own hostname.",
"remedy": "Send the request to one of the application's two managed hostnames, the production hostname or the development hostname whose first label ends in -dev, as list_applications returns them. Its custom domain serves requests too once read_status shows the domain serving. On the invoke endpoint nothing you do corrects this, because the platform's scheduled runs alone use that path."
},
{
"name": "unknown_route",
"surfaces": [
"storage"
],
"status": 404,
"owner": "OST-L0-02",
"summary": "The path is not one of the storage routes.",
"remedy": "Send the request to one of the storage routes. One file is at /storage/v0/areas/{area}/files/{name}, a listing at /storage/v0/areas/{area}/files, an area declaration at PUT /storage/v0/areas/{area}, and a transfer grant at POST /storage/v0/grants."
},
{
"name": "unknown_upstream",
"surfaces": [
"egress"
],
"status": 404,
"owner": "EGW-L0-01",
"summary": "The path has no upstream segment, or its upstream segment contains a NUL character (U+0000) or an unpaired surrogate.",
"remedy": "Send the call to /egress/v0/<upstream>/<path>, the declared upstream's name in place of <upstream>."
},
{
"name": "unrecognized_invitation",
"surfaces": [
"realm_surface",
"builder_sign_in"
],
"status": 403,
"owner": "ACS-L0-08",
"summary": "The realm accepts new accounts only by invitation, and the creation had no valid one. It had no invitation, one for another address, or one that is spent, expired, or revoked. The same name covers every case, on an end-user realm's surface and on the builder realm's sign-in page (ACB-L0-77).",
"remedy": "Sign in through the URL of a valid invitation, using the address it gives, or ask the realm's author for a fresh one, the platform's operator for the builder realm. If you are the author, read an invitation's state with list_invitations and issue a new one with invitation and act issue."
},
{
"name": "unsupported_token_type",
"surfaces": [
"builder_sign_in"
],
"status": 400,
"owner": "MCP-02",
"summary": "The builder sign-in's revocation endpoint, POST /oauth/revoke, received a token carrying a platform credential's prefix. This token form is not supported here; the prefix alone decides, without checking validity. Nothing is ended.",
"remedy": "End an OAuth connection here with its refresh or access token. End a minted or product token with revoke_token or on the dashboard. End an end-user session at its realm's revocation endpoint or by signing out. For another token form, use its issuing surface."
},
{
"name": "upgrade_not_served",
"surfaces": [
"router"
],
"status": 400,
"owner": "SVC-L0-22",
"summary": "A WebSocket upgrade arrived under `/__account/`, `/__router/`, or `/.well-known/`, the platform's own paths on an application hostname, which serve only ordinary requests. Nothing was forwarded to the application.",
"remedy": "Open the connection on a path of the application's own."
},
{
"name": "upload_hash_mismatch",
"surfaces": [
"management_action",
"storage"
],
"status": 409,
"owner": "OST-L0-08",
"summary": "The bytes a write sends under a deploy upload's grant, or the stored file the upload's start reads, are not the zip whose SHA-256 the turnzero command's preparing `deploy` call gave as `zip_sha256`. A refused write writes nothing and leaves the grant unspent, and a refused start deploys nothing.",
"remedy": "Call `deploy_command` with the application, naming no environment, and run the command it answers once, as given, from the application's folder, or `command_windows` on Windows; it deploys and prints its progress, then read `read_status`.",
"members": {
"received_sha256": {
"type": "string",
"description": "The SHA-256 of the bytes refused, 64 lower-case hexadecimal characters: the body the write carried, or the stored file the start read."
},
"expected_sha256": {
"type": "string",
"description": "The SHA-256 the preparing `deploy` call gave as `zip_sha256`, 64 lower-case hexadecimal characters, which the upload's grant records."
},
"credential_kind": {
"type": "string",
"description": "The kind of the credential whose binding refused the bytes, transfer_grant: the upload's grant, at the write and at the start alike."
}
}
},
{
"name": "upload_not_found",
"surfaces": [
"management_action"
],
"status": 404,
"owner": "PLD-L0-86",
"summary": "deploy: the upload the call gives has no file that its own grant wrote. It was not uploaded yet, its grant expired unused, a later preparing call replaced it, or a deploy that has ended already read it. The command's start under the upload's grant is also refused with it before the grant's write lands.",
"remedy": "Call `deploy_command` with the application, naming no environment, run the line it returns once, as given, from the application's folder, and make the answer's `next` call. Where the detail says a deploy already read the upload, read that deploy's outcome with list_versions instead: a new deploy would deploy it again."
},
{
"name": "upstream_ended",
"surfaces": [
"router"
],
"status": 502,
"owner": "HST-L0-03",
"summary": "The application's process ended while the request was in flight. The intermediary in front of the process responded for it before any response header reached the client: the cluster's interceptor's 502 on the pod grain, or the cell ingress's 503 on the container grain. The serving router reports the ending only where the leg's response is that grain's fixed shape whole, and refuses with 502 and the elapsed duration. A response of any other shape, an application's own 502 or 503 among them, passes through untouched. The router's record gives the application, the host, the path, the grain, the intermediary's status, and the duration, and on a scheduled run the schedule and the run. The invoke envelope reports the ending as upstream_failed, with upstream_ended in its detail.\n\nOn a function leg, the function runtime ended the worker before a response header reached the client. The router recognizes the runtime's fixed empty 503 response and returns upstream_ended with the elapsed duration. A worker can end at a limit or at its own failure; this response does not distinguish them.",
"remedy": "Retry the request: the process restarts under the platform's supervision, and a retry reaches the restarted process. Read the router's upstream_ended record through read_logs with source router. Where the harness ended the process, read the container source's process_ended line, which gives the handler that did not yield.\n\nFor a function, a retry uses a fresh worker. Report repeated endings with the returned detail."
},
{
"name": "upstream_failed",
"surfaces": [
"router"
],
"status": 502,
"owner": "SVC-L0-07",
"summary": "The router's proxy to the application failed before any status reached the client. A function leg can also fail because the pool refused the router's request, its refusal format is unreadable to the router, or the resolve response supplies a function with no usable pool target. The function did not run in these cases.",
"remedy": "Retry the request. If the refusal repeats, report it with its detail, which gives the failure's code and never an address inside the platform's network."
},
{
"name": "upstream_key_is_bound",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "MAN-14",
"summary": "declare_outbound_api: a setting binds the credential name, in the bound application's recorded manifest, in either environment's serving row, or in a deploy, promote, or restart in flight to either. Its value is then injected into the container, and a key the gateway applies at its edge never is (EGW-L0-03). The detail gives the setting and where it is bound. Refused before the write, nothing was written; refused after it, the write is taken back, or remains as written where the detail says so. On submit_manifest, a binding recorded after the submission's check feeds an entry's credential once the entry is written. That write is taken back where it can be, the manifest stays recorded, and the detail lists the upstreams declared, those not, and any left in place.",
"remedy": "Store the upstream's key under another name and declare the upstream with that name. Or remove the binding from the manifest's settings and call submit_manifest. Then deploy or promote each environment whose running copy has the binding, once any act in flight with it has ended, and declare the upstream again. Include the upstream's `sdk_settings` in that call, or omit the member, which keeps them; `sdk_settings` null removes them and ends the upstream's egress keys. Where the detail says the declaration remains, declare it again with another credential name, or remove the binding. On submit_manifest, change the entry's credential_name or remove the binding, then submit the manifest again before the next deploy or promote."
},
{
"name": "upstream_scope_refused",
"surfaces": [
"egress"
],
"status": 403,
"owner": "EGW-L0-08",
"summary": "Your credential does not reach the upstream declaration. An upstream accepts its own application's credentials and an account-wide credential that no bounding grant bounds. A credential bounded by any of the bounding grants MAPI-16 lists, `tztrack`, `tzmesh`, and `device_sign_in` among them, reaches no upstream of the account (MAPI-16).",
"remedy": "Repeat the request with a credential the upstream accepts: an account-wide credential that no bounding grant bounds, or the credential of the application the upstream is bound to. For a wider reach, mint a second token from a signed-in session through mint_token; you cannot widen the token you have. For a token bounded by the synthetic_seed_purge, synthetic_estate, publication, feedback_queue, or issues grant, mint a token without the grant, or call from the owner's session."
},
{
"name": "upstream_timeout",
"surfaces": [
"egress"
],
"status": 504,
"owner": "EGW-L0-05",
"summary": "The upstream took longer than the gateway's time limit, which covers a streamed response's whole life. A streamed response ends with this refusal as its final event.",
"remedy": "Retry the request. If the refusal repeats, report it with its detail."
},
{
"name": "upstream_unreachable",
"surfaces": [
"egress"
],
"status": 502,
"owner": "EGW-L0-05",
"summary": "The connection to the upstream failed, its host resolved to no address, or the transport failed mid-stream. At the `report` level, the `issue-tracking` upstream also refuses with this name a successful response it cannot read as the wire's JSON object (EGW-L0-03).",
"remedy": "Retry the request. If the refusal repeats, report it with its detail."
},
{
"name": "usage_over_quota",
"surfaces": [
"management_action",
"router",
"storage",
"push"
],
"status": 429,
"owner": "ACB-L0-26",
"summary": "The application is over its stored-data ceiling, or a push send would pass its month's push quantity (ACB-L0-26). No size meets this refusal for backend actions or data transfer. A file put to an area bound to an application whose stored-data state is over is refused (OST-L0-05). So is deploy_files with a file, keeping nothing (OST-L0-01). A generate_image call with that application is refused before counting or sending anything to the provider, saving nothing (ACB-L0-93). Gets, lists and deletes continue. Stored data clears at the next successful daily check that reads it within the ceiling, or at a raised quantity. On the push surface, a send past the size's push-messages-capacity cell accepts nothing.",
"remedy": "For stored data, reduce stored files and database data, then wait for the next daily check to read the figure within. On the push surface, wait for the next UTC month's first instant. A larger size raises neither quantity."
},
{
"name": "user_suspended",
"surfaces": [
"management_action",
"realm_surface"
],
"status": 403,
"owner": "ACS-L0-08",
"summary": "The end user is suspended in this realm until reinstatement. The `sign_in_test_end_user` action returns it for a suspended test end user, and nothing is signed in.",
"remedy": "Nothing the end user does lifts the suspension. If you are the application's author, restore the user's standing with set_end_user_standing and standing active; the user can then sign in again."
},
{
"name": "version_already_serving",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "PLD-L0-43",
"summary": "roll_back: the version given is already production's serving version. A re-mint of the production platform credential is a production deploy's or `promote`'s act, not `roll_back`'s.",
"remedy": "Call roll_back with a different deployed version. For a server on two environments, promote the serving version to re-mint production's platform credential. For a serverless version with functions, deploy a new version and promote it instead. On a server with one environment, deploy again to re-mint the credential for the new version."
},
{
"name": "version_image_pruned",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "PLD-L0-63",
"summary": "promote, roll_back, restart_application: an image the act needs was deleted from the cell registry by retention. promote and roll_back use the version given; restart_application uses the environment's serving version and takes no version number. The cell registry keeps the images of the serving version and the twenty most recent deployed versions per environment. These acts reuse a deployed image and cannot run without it. The `list_versions` action returns `promotable` per row. A new deploy builds a new version.\n\nFor a serverless version, retention deletes the client files and, where it holds functions, the installed tree. A promote or rollback of that version is refused by this name. A serverless restart reads no image and does not return this refusal.",
"remedy": "For promote or roll_back, choose a version that list_versions marks promotable, or deploy the artifact again as a new version. For restart_application, deploy again to build a new version. On an application with two environments, promote the new version for production."
},
{
"name": "version_keeping_unsupported",
"surfaces": [
"management_action",
"storage"
],
"status": 400,
"owner": "OST-L0-01",
"summary": "version_keeping true refuses at v0: the surface retains no prior versions.",
"remedy": "Send the declaration again with version keeping declared false (version_keeping: false in declare_storage_area). No setting of yours turns version keeping on at this version."
},
{
"name": "version_mismatch",
"surfaces": [
"storage"
],
"status": 412,
"owner": "OST-L0-07",
"summary": "The conditional put gave a version that is no longer current. The refusal body gives current_version, the version now stored.",
"remedy": "Read current_version from the refusal body. If the write still applies over the stored content, send the put again with If-Match set to that version."
},
{
"name": "version_newer_than_serving",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "PLD-L0-43",
"summary": "roll_back: the version given is newer than production's serving version.",
"remedy": "Use promote to put the newer version on production with its checks. On an application with one environment, deploy that code again."
},
{
"name": "version_reused",
"surfaces": [
"management_action"
],
"status": 409,
"owner": "LC-04",
"summary": "A library publish's begin: an entry of the catalog keeps a version the served catalog already has under a different closure hash. A version identifies one set of bytes, so the begin writes nothing. The refusal gives the entry, the version, and both closure hashes, each only where it has a valid form.",
"remedy": "Bump the entry's version and run the publish again from `begin`, or restore the entry's bytes to the served closure. Do not retry the same version with different bytes.",
"members": {
"entry": {
"type": "string",
"description": "The name of the entry whose version is reused, left out where it is not in a library entry name's shape."
},
"version": {
"type": "string",
"description": "The version the entry keeps, which the served catalog already holds under another closure, left out where it is not in a version's shape."
},
"served_closure_hash": {
"type": "string",
"description": "The closure hash the served catalog records for the entry, left out where it is not 64 lower-case hexadecimal characters."
},
"incoming_closure_hash": {
"type": "string",
"description": "The closure hash this catalog states for the entry, left out where it is not 64 lower-case hexadecimal characters."
}
}
},
{
"name": "websockets_disabled",
"surfaces": [
"router"
],
"status": 503,
"owner": "SVC-L0-23",
"summary": "The serving router's WebSocket switch, its setting `ROUTER_WEBSOCKETS`, does not read `on`. The operator stopped upgrades, or the router serves the path before its estate's setting is applied (PLD-L0-93). Every upgrade on every application hostname is refused after the suspension and halt refusals, and the application's requests are served as before. The router's stop closes every open connection with code 1012 (SVC-L0-23).",
"remedy": "Nothing you do corrects this. Open the connection again later."
},
{
"name": "websockets_not_declared",
"surfaces": [
"router"
],
"status": 400,
"owner": "SVC-L0-22",
"summary": "The application's manifest declares no `websockets` member, so it accepts no WebSocket upgrade (MAN-15). The router refuses with this after `not_deployed` and the audience gate, so a gated application's declaration is never revealed before its 401. Nothing was forwarded to the application.",
"remedy": "Declare `websockets` in the manifest, the empty object for pages on the application's own hostname, and submit it with submit_manifest. The router reads the declaration within about 30 seconds, with no redeploy."
},
{
"name": "websockets_not_yet_served",
"surfaces": [
"router"
],
"status": 400,
"owner": "SVC-L0-22",
"summary": "The upgrade reached an environment placed on the pod grain, a development environment or a shared-0.5gb production environment, while the router's setting `ROUTER_WEBSOCKETS_POD` reads `off`, its default (PLD-L0-127; PLD-L0-128; PLD-L0-93). Environments on the pod grain on this estate do not serve upgrades yet, and the detail says so. The refusal lifts on each estate when the platform turns the setting on. Nothing was forwarded to the application.",
"remedy": "Test on an environment on the container grain, such as shared-1gb production. Nothing else you do corrects this; the refusal ends when the platform serves upgrades to the pod grain."
},
{
"name": "window_ended",
"surfaces": [
"router",
"harness"
],
"status": 504,
"owner": "HST-L0-03",
"summary": "The request ran past the bounded execution window, the platform's configuration keyed by invocation kind (HST-L0-02). Where no response header has reached the client, the serving router refuses with 504 and the elapsed duration. Where the response is streaming, the router cuts the application leg. The router's record gives the application, the host, the path, and the duration, and on a scheduled run the schedule kind, the schedule, and the run. The harness's own line in the container's log says whether the handler yielded on its signal. Where the handler did not yield within the grace, `process_ended` lists the requests the process end cut beside it. The harness records this refusal and never sends it.",
"remedy": "Read the router's window_ended record through read_logs with source router for the path and the duration, and the container source for whether the handler yielded on its signal. Make that handler finish inside the window, ending its response when request.signal aborts."
},
{
"name": "workflow_keys_unavailable",
"surfaces": [
"workflow_start"
],
"status": 503,
"owner": "PLD-L0-76",
"summary": "The start-line route could not verify the run's token against GitHub's published key set, which could not be read or had no key of the token's key id yet. So the line was not stored.",
"remedy": "Post the line again; the start-line script retries once on its own."
},
{
"name": "workflow_not_admitted",
"surfaces": [
"workflow_start"
],
"status": 403,
"owner": "PLD-L0-76",
"summary": "The run's token verified, but the start-line route does not accept one of its claims. It gives another repository or owner than the plane's setting, a ref other than the trunk's, an unlisted workflow file, or a reusable workflow's reference. The detail gives the check.",
"remedy": "Nothing you do corrects this for that run. Only a run of a listed workflow file, in the repository the plane's setting gives and on its trunk, records a start."
},
{
"name": "workflow_token_invalid",
"surfaces": [
"workflow_start"
],
"status": 401,
"owner": "PLD-L0-76",
"summary": "The run's token did not verify: its signature, its algorithm (only RS256), its issuer, its audience, or its instants, read under the route's clock tolerance. The detail gives the check.",
"remedy": "Request a fresh token for the start-line route's audience in the same run and post it again."
}
]
}