# Errors

Every API error is an RFC 9457 problem with a stable code to branch on.

{/* Generated by scripts/reference.mjs from generated/*.json. Do not edit. */}

Query parameters are strict: booleans are `true`/`false` (or `1`/`0`), numbers must sit in the documented range (`tail` 1 to 10000), durations look like `10m`. Anything else is `400 bad_request` naming the parameter, never a silent default.

## Problem details [#problem-details]

Errors are RFC 9457 problem details, `Content-Type: application/problem+json`:

```json
{ "type": "https://docs.parity.ninja/reference/errors#not_ready", "title": "Not ready", "status": 409,
  "detail": "Sandbox ha1 is not ready yet (...)", "code": "not_ready", "retryable": true, "retry_after": 5 }
```

`code` is an extension member and stays the stable thing to branch on; `type` is `https://docs.parity.ninja/reference/errors#<code>`. `retryable` says whether the same request may succeed later, and `retry_after` (with the `Retry-After` header) says when. Some problems add members: `id` and `token` when a create failed after the sandbox existed, `log_tail` on `dependency_failed`.

## Codes [#codes]

| Code | Status | Retryable | Meaning |
| --- | --- | --- | --- |
| <a id="access_denied"></a>`access_denied` | 400 | no | The GitHub authorization was cancelled. |
| <a id="bad_request"></a>`bad_request` | 400 | no | The request is malformed: a bad argument, duration or JSON. |
| <a id="batch_unsupported"></a>`batch_unsupported` | 400 | no | An MCP request sent as a JSON-RPC batch; send one message per request. |
| <a id="code_invalid"></a>`code_invalid` | 400 | no | GitHub sent no authorization code, or rejected it as used or expired. |
| <a id="invalid_body"></a>`invalid_body` | 400 | no | The request body isn't valid JSON for this call; the message says where. |
| <a id="invalid_email"></a>`invalid_email` | 400 | no | Not an email address. |
| <a id="invalid_manifest"></a>`invalid_manifest` | 400 | no | parity.yaml failed to parse or validate. |
| <a id="invalid_org"></a>`invalid_org` | 400 | no | An org slug outside lowercase letters, digits, `-`, `_` and `.`. |
| <a id="invalid_password"></a>`invalid_password` | 400 | no | A password past 72 bytes. |
| <a id="invalid_redirect"></a>`invalid_redirect` | 400 | no | A sign-in redirect that isn't an http(s) URL. |
| <a id="not_a_member"></a>`not_a_member` | 400 | no | The user isn't a member of that org in the sandbox's auth. |
| <a id="note_required"></a>`note_required` | 400 | no | A freeze without a note. |
| <a id="state_expired"></a>`state_expired` | 400 | no | The GitHub connect link expired. Start again from the console. |
| <a id="state_mismatch"></a>`state_mismatch` | 400 | no | The GitHub connect link was started by another account. |
| <a id="unknown_source"></a>`unknown_source` | 400 | no | The project has no uploaded source with that digest. |
| <a id="bad_signature"></a>`bad_signature` | 401 | no | A webhook whose signature doesn't match. |
| <a id="unauthorized"></a>`unauthorized` | 401 | no | No token, or not a live one. |
| <a id="bad_origin"></a>`bad_origin` | 403 | no | A console write that didn't come from the console's own page. |
| <a id="egress_not_approved"></a>`egress_not_approved` | 403 | no | A sandbox token's sync allows an egress host that the promoted manifest doesn't. The allowlist comes from the promoted manifest. |
| <a id="forbidden"></a>`forbidden` | 403 | no | The token or its role can't do this; `permission` names what's missing when it is a role. |
| <a id="installation_not_admin"></a>`installation_not_admin` | 403 | no | Only an owner of the GitHub account can connect it. |
| <a id="installation_not_yours"></a>`installation_not_yours` | 403 | no | GitHub didn't list this installation for the signed-in user. |
| <a id="wrong_project"></a>`wrong_project` | 403 | no | The token, the manifest, the path or the sandbox name different projects. |
| <a id="wrong_sandbox"></a>`wrong_sandbox` | 403 | no | A sandbox token used on another sandbox, or on a sandbox recreated since the token was made. |
| <a id="environment_not_found"></a>`environment_not_found` | 404 | no | No environment. |
| <a id="installation_not_found"></a>`installation_not_found` | 404 | no | The GitHub account isn't connected to this organization. |
| <a id="no_app"></a>`no_app` | 404 | no | The project has no manifest yet: send its parity.yaml. |
| <a id="no_auth"></a>`no_auth` | 404 | no | The sandbox has no auth resource. |
| <a id="no_inbox"></a>`no_inbox` | 404 | no | The sandbox has no mail resource. |
| <a id="not_found"></a>`not_found` | 404 | no | No such sandbox, record, proof, run or path that this token can read. |
| <a id="not_frozen"></a>`not_frozen` | 404 | no | Lifting a freeze on an environment that has none. |
| <a id="project_not_found"></a>`project_not_found` | 404 | no | No project with this name that the token can read. |
| <a id="release_not_found"></a>`release_not_found` | 404 | no | Release not found. |
| <a id="step_not_found"></a>`step_not_found` | 404 | no | No such step. |
| <a id="user_not_found"></a>`user_not_found` | 404 | no | No user with that email in the sandbox's auth. |
| <a id="method_not_allowed"></a>`method_not_allowed` | 405 | no | The path exists but not with this method. |
| <a id="already_exists"></a>`already_exists` | 409 | no | A sandbox with this id exists in another project. (In the token's project, create converges it.) |
| <a id="already_promoted"></a>`already_promoted` | 409 | no | Already promoted. |
| <a id="conflict"></a>`conflict` | 409 | yes | A concurrent change, or an idempotent retry whose token was replaced. |
| <a id="deploy_frozen"></a>`deploy_frozen` | 409 | no | The environment is frozen. The message has the note, who froze it and since when; `freeze` in the body has the same. Lift it (`parity unfreeze`) or ask the person who set it. |
| <a id="email_taken"></a>`email_taken` | 409 | no | A user with that email already exists in the sandbox's auth. |
| <a id="environment_declared"></a>`environment_declared` | 409 | no | Environment declared. |
| <a id="environment_not_declared"></a>`environment_not_declared` | 409 | no | Environment not declared. |
| <a id="expiring"></a>`expiring` | 409 | no | The sandbox is being torn down. |
| <a id="installation_linked_elsewhere"></a>`installation_linked_elsewhere` | 409 | no | The GitHub account is connected to another Parity organization. |
| <a id="last_admin"></a>`last_admin` | 409 | no | The change would leave the organization without an Admin. Make someone else Admin first. |
| <a id="managed_by_idp"></a>`managed_by_idp` | 409 | no | The member is provisioned by the organization's IdP over SCIM. Unassign them from Parity in the IdP. |
| <a id="max_ttl"></a>`max_ttl` | 409 | no | An extend past the manifest's `max_ttl`. |
| <a id="name_taken"></a>`name_taken` | 409 | no | A project with this name exists. |
| <a id="no_history"></a>`no_history` | 409 | no | Nothing to roll back to. |
| <a id="no_source"></a>`no_source` | 409 | no | The project has no repository connected. |
| <a id="not_ready"></a>`not_ready` | 409 | yes | Services are still starting; `Retry-After` says when to look again. |
| <a id="release_finished"></a>`release_finished` | 409 | no | Release finished. |
| <a id="rollout_superseded"></a>`rollout_superseded` | 409 | no | Rollout superseded. |
| <a id="sandbox_failed"></a>`sandbox_failed` | 409 | no | The sandbox failed to start. |
| <a id="source_linked"></a>`source_linked` | 409 | no | This repository manifest already backs another project; `project` names it. |
| <a id="step_not_waiting"></a>`step_not_waiting` | 409 | no | Step not waiting. |
| <a id="too_many_proofs"></a>`too_many_proofs` | 409 | no | The sandbox already has the most proof bundles allowed (20). |
| <a id="unexpected_mail"></a>`unexpected_mail` | 409 | no | `inbox/wait?none=true`: a matching message arrived; `message` names it. |
| <a id="upstream_not_ready"></a>`upstream_not_ready` | 409 | no | Upstream not ready. |
| <a id="installation_gone"></a>`installation_gone` | 410 | no | Parity was uninstalled from this GitHub account. |
| <a id="too_large"></a>`too_large` | 413 | no | A request body, a proof file or a proof bundle past its size limit. |
| <a id="idempotency_mismatch"></a>`idempotency_mismatch` | 422 | no | An `Idempotency-Key` reused for a different create. |
| <a id="invalid_name"></a>`invalid_name` | 422 | no | A name that isn't a lowercase DNS label: letters, digits and `-`, starting with a letter, at most 63 characters. |
| <a id="invalid_path"></a>`invalid_path` | 422 | no | A manifest path that isn't a path in the repository ending in `.yaml` or `.yml`. |
| <a id="name_mismatch"></a>`name_mismatch` | 422 | no | The manifest sets a different `project:` than the name asked for. |
| <a id="rejected"></a>`rejected` | 422 | no | Parity refused the change as invalid. |
| <a id="repo_unreachable"></a>`repo_unreachable` | 422 | no | Parity couldn't read the repository or its manifest; the message says why. |
| <a id="reserved_name"></a>`reserved_name` | 422 | no | The name is reserved. |
| <a id="token_failed"></a>`token_failed` | 422 | no | Parity couldn't create the project token. Retry. |
| <a id="dependency_failed"></a>`dependency_failed` | 424 | no | A job failed; `log_tail` has its log. |
| <a id="rate_limited"></a>`rate_limited` | 429 | yes | Too many requests: this token's rate, too many invalid tokens from one address, or GitHub's rate limit. `Retry-After` says when. |
| <a id="too_many_requests"></a>`too_many_requests` | 429 | yes | The token has too many requests in flight. |
| <a id="too_many_waits"></a>`too_many_waits` | 429 | yes | The token, or the server as a whole, has too many long-polls open. |
| <a id="internal"></a>`internal` | 500 | yes | Parity failed unexpectedly. Retry; if it persists, report the time and the call. |
| <a id="revoke_failed"></a>`revoke_failed` | 500 | yes | The membership change is saved, but some of the person's tokens weren't revoked. Retry the same request. |
| <a id="no_store"></a>`no_store` | 501 | no | This server keeps no records of this kind. |
| <a id="not_implemented"></a>`not_implemented` | 501 | no | This server doesn't offer this call. |
| <a id="not_recorded"></a>`not_recorded` | 501 | no | This server has no egress report for the sandbox. |
| <a id="auth_unreachable"></a>`auth_unreachable` | 502 | yes | The sandbox's auth resource didn't answer. |
| <a id="cluster_error"></a>`cluster_error` | 502 | yes | Parity's backend failed; retry. |
| <a id="exec_failed"></a>`exec_failed` | 502 | yes | The exec stream failed before the command ran. |
| <a id="github_unavailable"></a>`github_unavailable` | 502 | yes | GitHub answered with an error or not at all; the message has its status. |
| <a id="inbox_unreachable"></a>`inbox_unreachable` | 502 | yes | The sandbox's mail resource didn't answer. |
| <a id="inbox_unreadable"></a>`inbox_unreadable` | 502 | no | A message couldn't be parsed. |
| <a id="activity_unavailable"></a>`activity_unavailable` | 503 | yes | Parity can't record this change right now, so it refused it. Reads still work; retry after `Retry-After`. |
| <a id="busy"></a>`busy` | 503 | yes | Too many source uploads in progress. Retry after `Retry-After`. |
| <a id="github_not_configured"></a>`github_not_configured` | 503 | no | The Parity GitHub App isn't set up on this server. |
| <a id="logs_unavailable"></a>`logs_unavailable` | 503 | yes | The log store can't be read right now. Without `q` or `until`, recent logs still come from the running services. |
| <a id="members_unavailable"></a>`members_unavailable` | 503 | yes | This Parity runs without the control database, so organizations and members can't be read or changed. |
| <a id="redaction_unavailable"></a>`redaction_unavailable` | 503 | yes | Parity couldn't read this sandbox's generated secrets to redact the output, so it ran and returned nothing. Retry after `Retry-After`. |
| <a id="store_error"></a>`store_error` | 503 | yes | The record store failed. |
| <a id="timeout"></a>`timeout` | 504 | yes | A wait or a command reached its timeout or the server's cap. |