---
title: Feedback
description: Report a problem with the platform from your AI tool, attach the refusal and its reference, and check the report's status later by its id.
slug: /guides/feedback
order: 6
visibility: public
redirects_from: []
---

# Feedback

Prompt:

> That refusal made no sense to me. File it with the platform.

Also works:

- "File feedback with Turn Zero describing what friction, gaps, or issues you found. Make suggestions on how they could improve their service."
- "Report that the storage guide never says how big a transfer can be."
- "Tell the platform we had to work around an unclear error."
- "What happened to the report we filed yesterday?"

## What your AI tool does

Your AI tool does each of these with no browser approval:

- Files a [report](https://turnzero.ai/cloud/concepts/glossary/#issue-and-report) with `submit_feedback`. The report is the tool's own, or yours when you dictated it and the tool works under your signed-in session. It attaches the evidence: the action, the [refusal](https://turnzero.ai/cloud/concepts/glossary/#refusal) name, and the refusal's `reference`.
- Files one whenever something got in its way: an unexpected refusal, a workaround it needed, a missing capability, or a missing page. The platform welcomes these reports.
- Quotes nothing of your own content and puts no personal details in a report. The text says what was attempted and what came back.
- Reads a report's status later with `read_feedback`, by the id the filing returned. Once the platform says the fix is live, it tries the refused call again.
- Adds to a report you filed, or answers a question the platform asked about it, by calling `submit_feedback` again with the same `problem_key` and the new text. The filing joins the same issue as a further report. A reporter has no comment action on the platform's space, so its reports are the channel.
- Corrects or withdraws a report you filed by calling `submit_feedback` with `amends`, the report's number, and the corrected words, or `withdraws: true` ([step 3](#3-add-to-a-report-correct-or-withdraw-it-or-join-it-to-an-issue)).

## What you need

- The refusal you want to report, exactly as your AI tool showed it to you. A management action's refusal includes a ten-character reference code. Keep a copy of it.

## Before your AI starts

**For the AI tool:** Check the following before starting.

- A signed-in session in your connected tool, or an account-scoped [minted token](https://turnzero.ai/cloud/concepts/glossary/#minted-token) ([Connect your AI assistant](https://turnzero.ai/cloud/getting-started/connect-your-tool/)). A token scoped to one application is refused `token_scope_refused` on every feedback action. That application's backend reaches its own issue space through the [egress gateway](https://turnzero.ai/cloud/concepts/glossary/#egress-gateway) instead.
- The refused call's action, refusal name, and `reference`, read from the refusal itself.

## Steps

The platform keeps feedback as issues and reports. An issue records one problem. A report is one filing about an issue, in the filer's own words, and is never edited. Several reports can belong to one issue.

The platform's issue service stores issues in issue spaces. Unless you name another space, your reports go to the platform's own space, where the platform team reads them.

### 1. File a report

A report carries no personal details: no names, email addresses, telephone numbers, or anything else that identifies a person. Leave out of a report anything you do not want us to have, or do not file the report. Your AI coding tools quote nothing of yours in a report of their own. The names of actions, refusals, applications, and files are not personal details.

Call `submit_feedback`. In this example, the tool files its own report about a refused `deploy` and copies the evidence from the refusal. The reference is an invented example of its form.

```json
{
  "source": "agent",
  "kind": "bug",
  "title": "deploy refused health_path_unserved although server.mjs answers /health",
  "text": "Called deploy for a new application. The refusal said no source file names the health path's last segment, but server.mjs at the zip's root answers GET /health.",
  "impact": "worked_around",
  "workaround": "Moved the health route into a file named health.mjs.",
  "evidence": { "action": "deploy", "refusal": "health_path_unserved", "reference": "3f9c2a7b1d" }
}
```

The members `submit_feedback` takes:

| Member | What it contains |
| --- | --- |
| `source` | Required. `agent` for the tool's own filing, `person` for a report you dictated, or `system` for a program's filing. Only your signed-in session can file as a person. Under a minted token, `person` is filed as `agent`, with the same origin as an agent's filing. |
| `provider`, `session` | Optional, for `agent`: the tool's provider name and its session id. Give both or neither. |
| `kind` | Required. Use `bug`, `gap` for a capability you needed and could not find, `docs` for a missing or wrong page, `friction` for something that works but is hard, or `praise`. Use `idea` for a suggestion. The aliases `missing_capability`, `documentation_gap`, `refusal_not_understood`, `problem`, `error`, `mistake`, and `usability` are also accepted. |
| `title` | Required. Up to 200 characters. |
| `text` | Optional. What was attempted and what came back, with no personal details, up to 20,000 characters. |
| `impact` | Optional. What the problem cost you: `blocked`, `worked_around`, `annoyed`, or `none`. |
| `workaround` | Optional. What you did to get past it, up to 4,000 characters. |
| `proposed_resolution` | Optional. The fix you would suggest, up to 4,000 characters. |
| `evidence` | Optional. `action`, `refusal`, `reference`, `code_site`, and a `context` of up to 20 short strings under keys of lowercase letters, digits, and underscores. The older `environment` and `version` give the build you saw. Any other member is refused. The refusal gives the members `evidence` takes or, for a long list, their count and the action's reference page. |
| `labels` | Optional. Up to 20 short lowercase labels. The label `synthetic` marks the platform’s own test reports. Without `space`, it is refused `invalid_request` unless your account is synthetic. On a space you name, it is an ordinary label. |
| `restricted` | Optional. `true` for a security concern. A reporter's read, such as `read_feedback` on the platform's space, then never returns the issue to any other reporter. |
| `problem_key` | Optional. Your own name for the problem. A later filing with the same name and different words adds a report to the same issue. One whose words and evidence both match the earlier report's is answered `retried` and adds nothing. Praise is the exception: praise and a report of another kind under the same name go to separate issues. If you leave it out, the platform makes one from the kind, the title, and the evidence's action and refusal. |
| `files` | Optional. Up to 4 screenshots, each a PNG, JPEG, or WebP file of at most 524,288 bytes that you stored first. Each names its `application`, `area`, `name`, and `environment`. A missing `environment` means the application's deploy target. |

To attach a screenshot, store it first. Call `mint_upload_grant` for an application of your account and an area bound to it, run the put line it returns, and name the stored file in `files`. The put line is the one-line command that uploads the file.

Before it files anything, the platform reads each file under your own sign-in or token. If it cannot find a file, or a file is larger than 524,288 bytes, the call is refused and nothing is filed. The image is stored with your report as you sent it, and no page of the platform shows it.

`submit_feedback` refuses `question` and `task` from a customer. An operator-granted Contributor uses the tzTrack tools for the group's tasks, as [Testing with a granted group](#testing-with-a-granted-group) explains.

The response contains your `report` as filed, the `issue` it belongs to, and an `outcome`:

- `filed`: a new issue was opened for it.
- `linked`: the report joined an existing issue.
- `retried`: the same filing arrived again, and nothing changed.
- `noted`: praise, recorded and closed at once.
- `confirmed`: you called again with `report` and `repeat_of`, and your report now belongs to the issue you named (step 3). On the platform's own space, where that issue was merged as a duplicate, your report belongs to its master instead. The master is the issue the duplicate was merged into.
- `amended`: you called with `amends`, and your correction or withdrawal was filed as a further report beside the one it amends (step 3).
- `related`: you sent `repeat_of`, and one of the two is praise and the other is not. Nothing is joined. Your report stays on its own issue, which the response returns as `issue`. The two issues are marked related unless either is restricted. No member of the response names that relation.

The filing answer's `issue.live_in` is null even if the fix is released; read the build with `read_feedback` in [step 2](#2-read-its-status).

On the platform's own space, `candidates` is an empty list. The platform team links your report to any issue it repeats when the team triages it, that is, reads and sorts it. `issue` is null when your report belongs to a restricted issue, including when your own filing set `restricted`. Your `report` and the `outcome` are still returned. `masked` lists the kinds of credential the service found in your text and hid. Replace each of those credentials with a new one.

`personal_removed` lists the kinds of personal detail the platform removed from your report before storing it: `email_address`, `telephone_number`, or `card_number`, in that order. Each detail is replaced by a mark, such as `[email address removed]`, and the list is empty when nothing was removed. [What is kept](#what-is-kept) says where each kind is removed.

### 2. Read its status

To read your submission in the platform's space, call `read_feedback` with `issue` set to the id the filing returned. Leave out `space`. The id below is an example.

```json
{ "issue": "#4127" }
```

On the platform's space, the response shows the issue as a reporter sees it:

- its `state`: `new`, `open` once it has been triaged, `waiting` while it needs something before it can move on, `fixed` once the change that fixes the issue lands, or `closed`;
- its `outcome` once closed, such as `verified`, `done`, `as_designed`, `declined`, or `duplicate`;
- a one-sentence `sentence` that describes the state and outcome in words;
- the `workaround`, when the platform team wrote one;
- the `note_to_reporters`, a message written for everyone who reported the issue, or null. In it, the platform team asks a question or gives news, in any state. On the platform's own space, a note that carries a [rule code](https://turnzero.ai/cloud/concepts/glossary/#rule-code), a decision number, or any code written the same way is held back and reads null. Such a code is capital letters, a hyphen, and a number. A note in plain words is shown. When a fix lands, its note gives the landing's time and commit. That note shows while the issue is `fixed`, or `closed` `done` or `verified`;
- `live_in`, the build the fix is live in, or null if no released build carries the fix yet;
- your own reports on it, and never another reporter's words.

[What changed](https://turnzero.ai/cloud/getting-started/what-changed/) also lists, by issue number, the reported fixes each release carried, a restricted issue excepted. Find your issue's number there, then read its state with `read_feedback`.

Reading a report another account filed is refused `not_found`. So is reading an issue number someone quotes to you that differs from the id `submit_feedback` returned to you. If one of your own reports joined that issue, the refusal may name your own submission for it. Call `read_feedback` with that id to read it. The refusal only ever names an issue you can read. For another account's issue, a restricted issue, or a number no issue has, it names nothing, so all three look the same.

Call `read_feedback` with no argument to list your own submissions. Add `state` to list only one state, or `query` to search your own reports' titles and texts, never the issue's title or summary. For paging with `limit` and `cursor`, follow [the paging instructions below](#feedback-in-your-application-s-space). Each list entry gives `id`, `state`, and `outcome`. Its `title`, when present, comes from your latest visible report that has one, never another reporter's report or the master issue's title.

Pass `detail: true` with a list or search to read its full entries within your existing access. To read one submission in full, pass its `issue` id and leave out `detail`. Nothing is deleted when the state moves, and a closed issue stays readable.

### 3. Add to a report, correct or withdraw it, or join it to an issue

To add to a report you filed, or answer the platform's question about it, call `submit_feedback` again with the same `problem_key` and new text. It joins the same issue as a further report. The question appears in `note_to_reporters`. If the team awaits your answer, the filing returns the issue to its queue. These feedback calls provide no comment or task-work action.

To correct a report you filed, call `submit_feedback` with `amends` set to the report number from the filing response. Send the fields to correct. You can include `kind`, `labels`, and `product` as well as `title`, `text`, `impact`, `workaround`, or `proposed_resolution`. Use the same `kind` values as for a new report. A report about the platform cannot use `question` or `task`. To withdraw a report filed in error, send `withdraws: true` with `amends`. The example below withdraws report 57, an invented number.

```json
{ "source": "agent", "amends": 57, "withdraws": true, "text": "Filed against the wrong application." }
```

The correction is filed as a further report beside the one it amends. The first report stays as you filed it, and the platform team reads the two side by side. The correction joins every issue the first report belongs to at that moment, and the response's `outcome` reads `amended`.

If you omit `kind`, `title`, `text`, `impact`, `workaround`, or `proposed_resolution`, the amendment uses that field from the latest amendment that did not withdraw the report. If there is none, it uses the original. A withdrawal with no `impact` has none. Send `null` to clear `text`, `workaround`, or `proposed_resolution`. An empty string clears `text` too. Evidence stays on the original report.

If you send `labels` or `product`, include every filing label you want to keep. `product` adds `product:<name>` to the list you send in `labels`. If you send only `product`, that list contains only the product label. This list replaces the filing labels on the issue your original report opened. If the platform team has set that issue's labels, its list stays in place.

A withdrawal changes nothing by itself. The platform team reads it and settles the issue. Send `withdraws: false` to take back a withdrawal. An amendment refuses `evidence`, `problem_key`, `restricted`, `report`, `repeat_of`, and `files` with `invalid_request`. Amending a report another account filed returns HTTP 404 (`not_found`), just like a report number that does not exist.

When you know which issue your report repeats, such as the issue an earlier report of yours belongs to, you can join the report to it. Call `submit_feedback` again with `report` set to your report's number and `repeat_of` set to that issue's id. A new filing can also name `repeat_of` directly, which adds it to that issue as a further report.

A new filing's response then carries `repeat_of` where the platform joined your report to that issue on this call. If the platform had already linked the report to that issue when it was filed, the response carries no `repeat_of`. If one of the two is praise and the other is not, your report keeps its own issue, the outcome reads `related`, and the response carries no `repeat_of`.

On the platform's own space, `repeat_of` can name only an issue that holds one of your own reports. There, an issue merged as a duplicate counts as its master: your report joins the master, and the response's `issue` and any `repeat_of` give the master. A `repeat_of` that names a restricted issue, an issue that holds none of your reports, or no issue at all is refused 404 `not_found`. The lookup counts against `read_feedback`'s per-minute limit. The report is still filed: send the same call without `repeat_of` to get it back.

### Testing with a granted group

Turn Zero's operator may grant a test group access to the company's feedback space. Find it through `list_issue_spaces` or `tztrack_list_spaces`; no space ID needs handing over. Each row gives `level`, its name in `role`, `restricted`, the group's `accounts`, admitted `actions` and `owner`, which is null there.

Viewer (`view`) reads, Reporter (`report`) also files, and Contributor (`contribute`) also works tasks the group opened. Use the tzTrack tools for that task work: file a task, update it, close it with an outcome its state permits, except `duplicate`, and reopen it. `submit_feedback` remains findings-only and refuses a task.

The grant reads only the group's reports, never restricted issues or another account's titles, comments or counts. An issue outside that group is treated as one that does not exist. Other calls, including cache, relation changes and export, refuse `grant_required`. Each bounded filing creates a new issue, without joining it to an existing one. The company replies through the task's note to reporters because the company's comments stay hidden.

Only the operator's grant sets membership in that space; `share_space` cannot share it. Ordinary feedback reads described above remain limited to your own submissions. [Sharing a space](https://turnzero.ai/tztrack/concepts/sharing-a-space/) explains the five role names and account bounds.

### Known issues in a refusal

A refusal can point to a known issue. When the platform team already knows about a refusal you receive, its `detail` ends with a sentence that gives the issue and any workaround. Once the fix is released, that sentence gives the build that includes it.

### What the platform adds to a report

When your evidence quotes the `reference` of one of your own calls, the platform reads its own record of that call. It stamps a report about a refused or failed call on either of two grounds:

- the kind is `bug`; or
- the impact is `blocked`, the kind is neither `praise` nor `idea`, and the action is one the space you file into lists as critical.

It adds the action, the refusal, the place in its code that returned it, and the build that handled the call. The response contains `stamped: true`, and the evidence is marked `stamped`. The platform can match the report to others with the same cause, without anyone reading its text.

A report that meets neither ground is not stamped. A report about a call that succeeded or was held for your approval is not stamped either. The platform still adds the action and the build. The response says `stamped: false`, and the evidence is marked `claimed`. The record's values replace any `refusal` or `code_site` you wrote. A report about a refused call that meets neither ground carries the record's refusal and no code site. The platform never matches such a report to another only because both mention the same call.

The platform can find a call for 25 days after it was made. A reference it cannot find under your account stays as you wrote it, marked `claimed`. The day after you file, the platform checks a claimed reference again.

A report is marked `confirmed` only when it names the refusal and its `reference` quotes a call refused or failed under your account in the 24 hours before you filed. Both the report's kind and its issue's kind must also pass this test:

- `bug`; or
- neither `praise` nor `idea`, with the report's impact `blocked` and the action listed as critical in the platform's issue space.

Otherwise the report stays `claimed`, and nothing else about it changes. An old report with no kind uses its issue's kind.

A blocked report with stamped or confirmed evidence about a critical action can reach priority 1 without waiting for a triage pass. That rule acts on a `bug`, `friction`, `gap`, or `docs` issue that is not closed and that the report opens or joins by its fingerprint. It never changes a priority that a person or a session set. Repeating your own report under its problem key sets no priority by that rule.

A refusal that includes a `reference` also includes `help`, the address of its row in the [refusals reference](https://turnzero.ai/cloud/reference/refusals/). Read its cause and remedy there before you file. Over MCP (Model Context Protocol, the connection your AI tool uses to call the platform), a refused result includes a second content block. That block gives the refusal and its reference, so your AI tool can copy them.

### What happens to a report after it is filed

The platform's triage passes read new reports with an AI model every five minutes. They record the issue's kind, the part of the platform it concerns, and its priority. They link a report to an issue it repeats, and merge duplicates where the platform's own records support the match. A report whose text reads as an instruction to whoever reads it is left for a person. Neither pass deletes a report or changes its text. The platform team also settles issues by hand. Your report's issue shows what was decided, whether by the passes or by a person.

A fixed issue closes as `verified` once the fix has been used. The platform counts calls of the same action that completed on a build that includes the fix, and your AI tool's retry is one of them. After a platform incident closes, the next daily pass files an issue for it. It links each report made while the incident was open, up to a limit. [What the triage passes do](https://turnzero.ai/cloud/guides/keep-your-own-issue-list/#what-the-triage-passes-do) describes the passes in full. They also run in your own spaces whose settings turn them on.

### What is kept

A report is kept as the platform's own record of the problems people meet when they build on it. It identifies the account that filed it. What you file becomes the platform's to keep and use, as the [terms of service](https://turnzero.ai/terms) say.

Before a report is stored, the platform takes reasonable measures to remove confidential details that someone pastes into it: email addresses, telephone numbers in international form, and payment card numbers. It does not guarantee that every such detail is removed. The rest of the text stays as written, including where it identifies you, so keep personal details out of it, as [step 1](#1-file-a-report) asks.

Where each kind is removed:

- Email addresses and telephone numbers are removed from the report's title, text, workaround, proposed resolution, and the technical details your AI tool attaches in each evidence `context` value.
- A payment card number is removed from the report's words alone. A `context` value keeps it, because the technical details hold the identifiers a fix needs, and a long number among them can look like a card number.
- The action, the refusal, the reference, and the code site in the evidence are never changed.

An image you attach is stored exactly as you sent it, because the platform cannot find personal details in an image, so crop out or leave out anything you do not want kept.

When the account is deleted, the account's identity is erased from every report it filed. No report is deleted, and each keeps its text as written.

The platform's triage passes read report text with an AI provider under the platform's own key. The [privacy page](https://turnzero.ai/privacy) lists who receives the text and how long it is kept.

## Your own issue spaces

Your account can have issue spaces of its own. Each stores issues and reports the same way the platform's own space does, for a repository's issue list or a program's test results. Every account has the tzTrack access needed to create one, mint its token, and work it through `relay_issue_act`. [Keep your own issue list](https://turnzero.ai/cloud/guides/keep-your-own-issue-list/) covers that task: the space, its token's grant levels, the operations the relay passes on, and how its issues get their priority.

Your AI tool lists `tztrack_create_space` and `tztrack_share_space`. A program calls `relay_issue_act` under the space's `issues` token; the AI tool's sign-in connection does not list that call. The feedback actions and `list_issue_spaces` stay listed too, so your applications' own spaces stay within reach.

## Feedback in your application's space

[Let your app's users send feedback](https://turnzero.ai/cloud/guides/let-your-apps-users-send-feedback/) adds a form and a backend route, then reads the reports through your AI tool. Start there to add feedback to your app.

An application that declares the `issue_tracking` service in its [manifest](https://turnzero.ai/cloud/concepts/glossary/#manifest) has a space of its own. Its backend files its users' reports there through the [Issue Tracking](https://turnzero.ai/cloud/backend-packages/tztrack/) client. That page describes the space: how reports are stamped with their environment and version, the build records, and what a deletion removes. [Bind an application to the space](https://turnzero.ai/cloud/guides/keep-your-own-issue-list/#bind-an-application-to-the-space) binds the application to a space of your account instead.

Your backend uses its application's own space at the `report` [grant level](https://turnzero.ai/cloud/concepts/glossary/#grant-level), so the responses it receives leave out every restricted issue. No deployment reads those restricted issues.

Your account's `read_feedback` call with `space` lists and reads restricted issues too. Reading one `issue` returns it whole, including every reporter's reports. Calling `relay_issue_act` under an `owner` token for that space is another way to read it.

The feedback actions can act on that space when you name it in `space`, with the id the response of `submit_manifest` gives. They can also act on any one space of an application that keeps a space for each environment, and a space your account owns.

- `submit_feedback` files into that space as your account's own actor.
- `read_feedback` lists the space's issues, reads one with `issue`, or selects a list with `queue: true` ([Reading the queue](https://turnzero.ai/cloud/guides/keep-your-own-issue-list/#reading-the-queue)).
- `settle_feedback` settles one of its issues, or triages one by setting its kind or component.

None of them needs a grant.

To list the space, call `read_feedback` with `space`. Without `query`, it lists issues newest first, in every state; add `state` to select one. Add `query` to search the issue's title, summary and reports for any word of the query. Search results sort by relevance, then newest first. A search also takes `state`, `kind` and `component`. Lists and searches also take `reporter_accounts`: 1 to 20 recorded reporter account IDs. Each issue appears once when a report the call can already read was recorded under one of those accounts. The filter only narrows what you can read.

Lists and searches return compact entries by default. Each gives `id`, `kind`, `title`, `state`, `outcome`, `priority`, `effective_priority`, `waiting_for`, `report_count`, `updated_at` and `restricted`, where the issue has them. `restricted` tells you whether the issue is restricted. `updated_at` dates the latest change, not a filing.

Add `detail: true` for full issue entries, including `created_at` and `last_reported_at`. To read an issue with its reports, pass `space` and `issue`, leaving out `detail` and `queue`. The platform-space restriction to your own reports in [step 2](#2-read-its-status) does not apply to this owner read.

For each list or search, `limit` sets the page size from 1 to 100, with 50 as the default. Pass the answer's `cursor` in the next call to read the next page. A null `cursor` means there is no next page.

A filing that names a `space` returns up to three existing issues your report may repeat, as `candidates`. Each has its id, its state, and any workaround a trusted actor wrote. A candidate's `title` is null in three cases: a report other than the platform team's own gave it, the platform team has not yet reviewed the issue, or a triage pass wrote the title.

Each candidate also carries the issue's `kind` and `component`, and its `summary` where a trusted actor wrote one. Its `matched_evidence` names the members of your `evidence`, such as `action` or `code_site`, that equal those of the existing reports whose evidence chose the issue, and none where only your title's words matched.

A candidate can be an issue closed `declined` or `as_designed`. Its `outcome` and its `sentence`, such as "Not taken.", mean the request was considered and not taken. Filing it again does not reopen it. A candidate's `outcome` is null while its issue is not closed.

A candidate with a null `title` asks nothing of you, because your report is already filed. Confirm a candidate with `repeat_of` only where you know it is the same issue. Otherwise nothing more is needed: the triage passes look for duplicates themselves.

All three actions refuse a token scoped to an application with `token_scope_refused`. That application's backend uses the space through the gateway at its grant level. A request that passes `application` or `environment` is refused `invalid_request`, and the refusal gives `space`. Pass the space in `space` instead. A `space` your account does not have is refused `not_found` before any credential is read, whoever has it.

The platform measures each space's stored bytes without reading any record's content. That measurement counts against no account or application limit. No charge applies to an issue space's stored data. Your account's export includes only your account's own filings in each space, not the records your end users filed there.

To keep those records before you delete the application, export the space with the `export` operation of `relay_issue_act` under an `owner` token for that space ([Keep your own issue list](https://turnzero.ai/cloud/guides/keep-your-own-issue-list/#6-export-before-anything-deletes-the-space)). That token requires tzTrack access. Without it, or where the application keeps a space for each environment, read the space with `read_feedback` instead. Read its issues page by page, then each issue's reports with `issue`. [Deletion and copies](https://turnzero.ai/cloud/backend-packages/tztrack/#deletion-and-copies) says what a deletion removes.

## Expected result

`submit_feedback` returns 200 with your `report`, an `issue` whose `state` is `new` or `open`, an `outcome` of `filed`, and a `reference` for the call itself. `read_feedback` with that issue's id returns the same issue with your report on it.

Over MCP, `read_feedback`, `submit_feedback`, `settle_feedback`, and `relay_issue_act` each return one block. The block opens with a marker that says its content is untrusted. The JSON stands between two delimiter lines, because the text inside is what reporters wrote.

`list_issue_spaces` also returns one such block, under a marker of its own, when it lists a space another account shares with you, because that space's name is text its owner wrote. If the list contains only spaces your account owns, application spaces, or the platform space, Cloud returns plain JSON. Cloud marks the result as untrusted if it cannot classify the listing. Every other call returns a JSON block.

## Refusals

See the [refusals reference](https://turnzero.ai/cloud/reference/refusals/) for other platform errors.

A refusal gives the action and its cause in `detail`. It files no report. The platform's record of the call keeps the refusal and its reference. [Keep your own issue list](https://turnzero.ai/cloud/guides/keep-your-own-issue-list/#refusals) lists the refusals of the issue-space actions.

| Refusal | Status | Cause | Remedy |
| --- | --- | --- | --- |
| `invalid_request` | 400 | A member breaks the rules in step 1, a file in `files` holds more than 524,288 bytes, or the request passed `application` or `environment`. `detail` gives the member to correct. | Correct the named member and call again. Name a space in `space`. |
| `feedback_rate_limited` | 429 | A limit was passed: the account's share in a minute, a space's limit, the platform's cap, or the issue service's own rate limit. `detail` says which. | Wait until the next minute starts, then repeat the call with the same key. The platform reads it as a retry, never as a second report. |
| `issue_service_unreachable` | 503 | The platform's issue service did not respond. `detail` gives the cause in one word. | Repeat the call after a short wait with the same `key`. |
| `not_found` | 404 | `read_feedback` named a submission that is not the account's own, or `space` matches no space your account has. A filing's `files` names a file that your call cannot read. | Use the submission `detail` names, where it names one, or an id from `read_feedback` with no argument. For a space, use the identifier that `submit_manifest` or `list_issue_spaces` returns. |
| `grant_required` | 403 | `read_feedback` with `queue`, or `settle_feedback`, was called on the platform's space. Only platform staff can do that, under the `feedback_queue` grant. | Call `read_feedback` without `queue` for your own submissions, or name your space. |
| `token_scope_refused` | 403 | The call came under a token scoped to one application, which no feedback action accepts. | Use the session or an [account-scoped token](https://turnzero.ai/cloud/concepts/glossary/#account-scoped-token). The application's backend reaches its space through the gateway. |
| `not_yet_provisioned` | 501 | The platform you reached runs no issue service, which every feedback action needs. So the actions are missing from your AI tool's list of actions. | Nothing on your side fixes this. Email support@turnzero.ai with the action, refusal name, and reference from the refused call. |

## Related

- [Keep your own issue list](https://turnzero.ai/cloud/guides/keep-your-own-issue-list/) creates an issue space of your account and works it through the relay.
- [What happens without asking](https://turnzero.ai/cloud/concepts/what-happens-without-asking/) explains which actions complete in the call and which a person approves first.
- [Sign-in, sessions, and tokens](https://turnzero.ai/cloud/concepts/sign-in-sessions-and-tokens/) explains which credentials file feedback.
- [Export or delete your account](/turnzero/guides/export-or-delete-your-account/) covers the export, which includes the account's own reports, and the deletion.
- [Actions](https://turnzero.ai/cloud/reference/action-catalog/) lists every management action a customer can call, with its payload and refusals.

For what you can share with the support agent, read [What Turn Zero support can see](https://turnzero.ai/cloud/concepts/what-turn-zero-support-can-see/).
