Skip to content
Reference
Markdown

Errors

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

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

Errors are RFC 9457 problem details, Content-Type: application/problem+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

CodeStatusRetryableMeaning
access_denied400noThe GitHub authorization was cancelled.
bad_request400noThe request is malformed: a bad argument, duration or JSON.
batch_unsupported400noAn MCP request sent as a JSON-RPC batch; send one message per request.
code_invalid400noGitHub sent no authorization code, or rejected it as used or expired.
invalid_body400noThe request body isn't valid JSON for this call; the message says where.
invalid_email400noNot an email address.
invalid_manifest400noparity.yaml failed to parse or validate.
invalid_org400noAn org slug outside lowercase letters, digits, -, _ and ..
invalid_password400noA password past 72 bytes.
invalid_redirect400noA sign-in redirect that isn't an http(s) URL.
not_a_member400noThe user isn't a member of that org in the sandbox's auth.
note_required400noA freeze without a note.
state_expired400noThe GitHub connect link expired. Start again from the console.
state_mismatch400noThe GitHub connect link was started by another account.
unknown_source400noThe project has no uploaded source with that digest.
bad_signature401noA webhook whose signature doesn't match.
unauthorized401noNo token, or not a live one.
bad_origin403noA console write that didn't come from the console's own page.
egress_not_approved403noA sandbox token's sync allows an egress host that the promoted manifest doesn't. The allowlist comes from the promoted manifest.
forbidden403noThe token or its role can't do this; permission names what's missing when it is a role.
installation_not_admin403noOnly an owner of the GitHub account can connect it.
installation_not_yours403noGitHub didn't list this installation for the signed-in user.
wrong_project403noThe token, the manifest, the path or the sandbox name different projects.
wrong_sandbox403noA sandbox token used on another sandbox, or on a sandbox recreated since the token was made.
environment_not_found404noNo environment.
installation_not_found404noThe GitHub account isn't connected to this organization.
no_app404noThe project has no manifest yet: send its parity.yaml.
no_auth404noThe sandbox has no auth resource.
no_inbox404noThe sandbox has no mail resource.
not_found404noNo such sandbox, record, proof, run or path that this token can read.
not_frozen404noLifting a freeze on an environment that has none.
project_not_found404noNo project with this name that the token can read.
release_not_found404noRelease not found.
step_not_found404noNo such step.
user_not_found404noNo user with that email in the sandbox's auth.
method_not_allowed405noThe path exists but not with this method.
already_exists409noA sandbox with this id exists in another project. (In the token's project, create converges it.)
already_promoted409noAlready promoted.
conflict409yesA concurrent change, or an idempotent retry whose token was replaced.
deploy_frozen409noThe 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.
email_taken409noA user with that email already exists in the sandbox's auth.
environment_declared409noEnvironment declared.
environment_not_declared409noEnvironment not declared.
expiring409noThe sandbox is being torn down.
installation_linked_elsewhere409noThe GitHub account is connected to another Parity organization.
last_admin409noThe change would leave the organization without an Admin. Make someone else Admin first.
managed_by_idp409noThe member is provisioned by the organization's IdP over SCIM. Unassign them from Parity in the IdP.
max_ttl409noAn extend past the manifest's max_ttl.
name_taken409noA project with this name exists.
no_history409noNothing to roll back to.
no_source409noThe project has no repository connected.
not_ready409yesServices are still starting; Retry-After says when to look again.
release_finished409noRelease finished.
rollout_superseded409noRollout superseded.
sandbox_failed409noThe sandbox failed to start.
source_linked409noThis repository manifest already backs another project; project names it.
step_not_waiting409noStep not waiting.
too_many_proofs409noThe sandbox already has the most proof bundles allowed (20).
unexpected_mail409noinbox/wait?none=true: a matching message arrived; message names it.
upstream_not_ready409noUpstream not ready.
installation_gone410noParity was uninstalled from this GitHub account.
too_large413noA request body, a proof file or a proof bundle past its size limit.
idempotency_mismatch422noAn Idempotency-Key reused for a different create.
invalid_name422noA name that isn't a lowercase DNS label: letters, digits and -, starting with a letter, at most 63 characters.
invalid_path422noA manifest path that isn't a path in the repository ending in .yaml or .yml.
name_mismatch422noThe manifest sets a different project: than the name asked for.
rejected422noParity refused the change as invalid.
repo_unreachable422noParity couldn't read the repository or its manifest; the message says why.
reserved_name422noThe name is reserved.
token_failed422noParity couldn't create the project token. Retry.
dependency_failed424noA job failed; log_tail has its log.
rate_limited429yesToo many requests: this token's rate, too many invalid tokens from one address, or GitHub's rate limit. Retry-After says when.
too_many_requests429yesThe token has too many requests in flight.
too_many_waits429yesThe token, or the server as a whole, has too many long-polls open.
internal500yesParity failed unexpectedly. Retry; if it persists, report the time and the call.
revoke_failed500yesThe membership change is saved, but some of the person's tokens weren't revoked. Retry the same request.
no_store501noThis server keeps no records of this kind.
not_implemented501noThis server doesn't offer this call.
not_recorded501noThis server has no egress report for the sandbox.
auth_unreachable502yesThe sandbox's auth resource didn't answer.
cluster_error502yesParity's backend failed; retry.
exec_failed502yesThe exec stream failed before the command ran.
github_unavailable502yesGitHub answered with an error or not at all; the message has its status.
inbox_unreachable502yesThe sandbox's mail resource didn't answer.
inbox_unreadable502noA message couldn't be parsed.
activity_unavailable503yesParity can't record this change right now, so it refused it. Reads still work; retry after Retry-After.
busy503yesToo many source uploads in progress. Retry after Retry-After.
github_not_configured503noThe Parity GitHub App isn't set up on this server.
logs_unavailable503yesThe log store can't be read right now. Without q or until, recent logs still come from the running services.
members_unavailable503yesThis Parity runs without the control database, so organizations and members can't be read or changed.
redaction_unavailable503yesParity couldn't read this sandbox's generated secrets to redact the output, so it ran and returned nothing. Retry after Retry-After.
store_error503yesThe record store failed.
timeout504yesA wait or a command reached its timeout or the server's cap.