Errors
102 error codes, each with what it means and the operations that return it.
ACCESS_ESCALATIONThe change would give someone more access than you hold yourself403
AGENT_HALTEDThe agent's AI organization is paused, or the agent is suspended401Agents only
In the body as
error.reasonNo operation lists it: it answers only the callers named above.
AGENT_REFAn AI agent moves only branches under its own `ai/<handle>/` prefix, and never a tag403Agents only
In the body as
error.reasonviolations[].codeNo operation lists it: it answers only the callers named above.
AGENTS_NEVER_DIRECT_PEOPLEAn AI agent assigns work only to agents of its own organization, never to a person403Agents only
In the body as
error.reasonNo operation lists it: it answers only the callers named above.
ALREADY_APPROVEDYou have already approved this step; it needs approvals from other people409
In the body as
error.reasonAPPROVAL_NOT_ACCEPTEDThis approval gate does not count your approval403
In the body as
error.reasonAPPROVAL_REQUIRES_PERSONOnly a person can give this approval403Agents only
In the body as
error.reasonNo operation lists it: it answers only the callers named above.
APPROVERS_NOT_IN_ENVIRONMENTA pipeline step names approvers its environment does not; a step may narrow its environment's approvers, not replace them400
In the body as
error.reasonBAD_GATEWAYA service the request depends on failed; retry later502Retryable
In the body as
error.codeBAD_REQUESTThe request is malformed: a parameter or a body field is not a well-formed value of its type400
In the body as
error.codeReturned by 678 operations — each operation's page lists it under its status.
BRANCH_EXISTSA branch with that name already exists409
In the body as
error.reasonviolations[].codeBRANCH_NOT_FOUNDThe branch does not exist, and nothing asked for it to be created404
In the body as
error.reasonviolations[].codeBRANCH_PROTECTEDA branch rule keeps you from changing this branch this way403
In the body as
error.reasonviolations[].codeCHECK_NOT_ATTESTABLEThe check is computed by the platform, so it cannot be attested by hand409
In the body as
error.reasonCONFIG_ERRORThe server is misconfigured; report it500
In the body as
error.codeNo operation lists it: it answers only the callers named above.
CONFLICTThe request conflicts with the resource's current state; `reason` says how409
In the body as
error.codeReturned by 347 operations — each operation's page lists it under its status.
CRITERIA_NOT_GREENThe work item's required acceptance criteria are not all satisfied409
In the body as
error.reasonCRITERION_IS_BOUNDThe criterion is bound to evidence a pipeline produces, so it cannot be ticked by hand; unbind it first409
In the body as
error.reasonDATABASE_ERRORThe server's data store failed; retry, and report it if it persists500Retryable
In the body as
error.codeNo operation lists it: it answers only the callers named above.
EVALUATION_NOT_RETRYABLEOnly a pipeline that should have started and could not can be retried; a merge request's pipelines are run again from the merge request409
In the body as
error.reasonEXTERNAL_REQUIRES_NO_PATHSAn external service is not built here, so it cannot claim repository paths400
In the body as
error.reasonEXTERNAL_WRITE_REQUIRES_PERSONAn AI agent does not change a public or internal resource; a person does403Agents only
In the body as
error.reasonNo operation lists it: it answers only the callers named above.
FILE_CHANGEDA file the change edits is no longer the version you read409
In the body as
error.reasonviolations[].codeFILE_EXISTSA file the change creates already exists409
In the body as
error.reasonviolations[].codeFILE_NOT_FOUNDA file the change updates, moves or deletes is not there404
In the body as
error.reasonviolations[].codeFORBIDDENYou are signed in but may not do this here; `reason` names the permission or the rule that refused it403
In the body as
error.codeReturned by 684 operations — each operation's page lists it under its status.
FOREIGN_AUTHORAn AI agent pushes only commits it authored403Agents only
In the body as
error.reasonviolations[].codeNo operation lists it: it answers only the callers named above.
GRANT_EXISTSThe person, service account or team already holds a different role here; change that grant instead409
In the body as
error.reasonHARD_FLOORAn AI agent may never make this decision; a person does403Agents only
In the body as
error.codeNo operation lists it: it answers only the callers named above.
HEAD_MOVEDThe branch moved since you read it; read it again and retry409
In the body as
error.reasonviolations[].codeIDEMPOTENCY_IN_FLIGHTA request with the same `Idempotency-Key` is still running; retry it shortly409RetryableAgents only
In the body as
error.codeNo operation lists it: it answers only the callers named above.
IDEMPOTENCY_KEY_INVALIDThe `Idempotency-Key` is not one this token may send403422Agents only
In the body as
error.codeNo operation lists it: it answers only the callers named above.
IDEMPOTENCY_KEY_REUSEDThe `Idempotency-Key` was already used for a different request422Agents only
In the body as
error.codeNo operation lists it: it answers only the callers named above.
IDP_GROUP_LINKEDAnother team of the organization already follows that identity-provider group409
In the body as
error.reasonIDP_GROUPS_NOT_MAPPEDThe organization's single sign-on connection sends no groups, so a team cannot follow an identity-provider group422
In the body as
error.reasonINSUFFICIENT_SCOPEThe access token lacks the scope this operation needs; `required_scope` names it403
In the body as
error.codeReturned by 684 operations — each operation's page lists it under its status.
INTERNAL_ERRORThe server failed; retry, and report it if it persists500Retryable
INVALID_BINDINGThe criterion binding is not well-formed400
In the body as
error.reasonINVALID_PATH_GLOBThe path glob is not valid400
In the body as
error.reasonLAST_ORGANIZATION_OWNERThe change would leave the organization with no Owner; make someone else an Owner first409
In the body as
error.reasonLEASE_STALEAnother runner holds this session now409Agents only
In the body as
error.reasonNo operation lists it: it answers only the callers named above.
LEGAL_ACCEPTANCE_REQUIREDAccept the current Terms of Service before changing anything; reading stays open409
In the body as
error.reasonReturned by 330 operations — each operation's page lists it under its status.
LEGAL_VERSION_NOT_CURRENTThat version is neither in force nor the one coming; accept the version you were shown from the current list409
In the body as
error.reasonLIMIT_EXISTSThe person, service account or team is already limited here; remove that limit first409
In the body as
error.reasonMCP_READ_ONLYThe MCP connection is read-only, and this operation changes something403MCP only
In the body as
error.codeNo operation lists it: it answers only the callers named above.
MERGE_CONFLICTSThe branches conflict; resolve the conflicts, then merge again409
In the body as
error.reasonMR_NOT_OPENThe merge request is merged or closed409
In the body as
error.reasonviolations[].codeNAME_HOLD_LIMITThe organization already holds back as many of its former names as it may; rename it back to one of them, or ask support to release one409
In the body as
error.reasonNAME_RESEMBLES_RESERVEDThe name looks like a name reserved for another organization; prove that organization's domain, or choose another name403
In the body as
error.reasonNAME_RETIREDAnother organization gave the name up recently, or published under it, so it is held back; choose another name409
In the body as
error.reasonNOT_A_USERA team is made of people; give a service account access directly instead422
In the body as
error.reasonNOT_AN_APPROVERYou may not approve this step403
In the body as
error.reasonNOT_AN_ORGANIZATIONOnly an organization — a top-level group — has teams and custom roles, and a name that can be reclaimed or held for it400
NOT_AWAITING_APPROVALThe step is not waiting for an approval409
In the body as
error.reasonNOT_CONFLICTEDThe merge request's branches merge cleanly; there is nothing to resolve409
In the body as
error.reasonviolations[].codeNOT_FOR_AGENTSAn AI agent may not call this operation403Agents only
In the body as
error.codeNo operation lists it: it answers only the callers named above.
NOT_FOUNDThe resource does not exist — or exists and you cannot see it: a private resource you have no access to answers exactly as an absent one does404
In the body as
error.codeReturned by 651 operations — each operation's page lists it under its status.
NOT_IMPLEMENTEDThis deployment has not configured the feature the operation needs; the message names it501
In the body as
error.codeReturned by 64 operations — each operation's page lists it under its status.
NOT_IN_CONFLICTA resolution names a file that does not conflict422
In the body as
error.reasonviolations[].codeNOT_REGRESSEDThe work item's verification has not regressed, so there is nothing to clear409
In the body as
error.reasonNOTHING_TO_COMMITThe change leaves every file as it was422
In the body as
error.reasonviolations[].codePATH_CONFLICTA path collides with the tree: a file where a directory is, or beneath a file409
In the body as
error.reasonviolations[].codePAYLOAD_TOO_LARGEThe request body is larger than this operation accepts413
In the body as
error.codePAYMENT_REQUIREDThe feature needs a paid plan402
In the body as
error.codePERMISSION_DEPENDENCYThe role would hold a permission without another permission it depends on422
In the body as
error.reasonNo operation lists it: it answers only the callers named above.
PERMISSION_REQUIREDYou need a permission you do not hold here; the message names it403
In the body as
error.reasonviolations[].codeReturned by 684 operations — each operation's page lists it under its status.
PIPELINE_VALIDATION_FAILEDThe pipeline definition is invalid; `violations` lists every problem, so all of them can be fixed at once400
In the body as
error.code- POST/groups/{group_id}/pipeline-components
- PUT/groups/{group_id}/pipeline-components/{component_id}
- POST/groups/{group_id}/pipeline-components/{component_id}/repin
- POST/groups/{group_id}/pipeline-components/{component_id}/versions
- POST/repositories/{repo_id}/pipeline-components
- PUT/repositories/{repo_id}/pipeline-components/{component_id}
- POST/repositories/{repo_id}/pipeline-components/{component_id}/repin
- POST/repositories/{repo_id}/pipeline-components/{component_id}/versions
- POST/repositories/{repo_id}/pipeline-runs
- POST/repositories/{repo_id}/pipeline-runs/{pipeline_run_id}/approve
- POST/repositories/{repo_id}/pipelines
- PUT/repositories/{repo_id}/pipelines/{pipeline_id}
- POST/repositories/{repo_id}/pipelines/{pipeline_id}/expand
- POST/repositories/{repo_id}/pipelines/{pipeline_id}/publish
- POST/repositories/{repo_id}/pipelines/{pipeline_id}/trigger
- POST/repositories/{repo_id}/trigger-evaluations/{evaluation_id}/retry
PIPELINES_NOT_GREENThe repository requires the merge request's pipelines to pass, and they have not all passed at its head yet; the message says which409
In the body as
error.reasonPRIVILEGED_PATHThe commit changes a file that governs how the repository is protected, which an AI agent does not change403Agents only
In the body as
error.reasonviolations[].codeNo operation lists it: it answers only the callers named above.
PROVIDER_VALIDATION_FAILEDThe pipeline uses a provider your organization's policy does not allow; `violations` lists each one403
In the body as
error.code- POST/repositories/{repo_id}/pipeline-runs
- POST/repositories/{repo_id}/pipeline-runs/{pipeline_run_id}/approve
- POST/repositories/{repo_id}/pipeline-runs/{pipeline_run_id}/retry
- POST/repositories/{repo_id}/pipelines/{pipeline_id}/trigger
- POST/repositories/{repo_id}/trigger-evaluations/{evaluation_id}/retry
PUSH_RULE_VIOLATIONA push rule refuses the change; `rule` names it422
In the body as
error.reasonviolations[].codeREPOSITORY_EMPTYThe repository has no branches or tags yet; there is nothing to read until something is pushed to it409
In the body as
error.codeerror.reasonviolations[].codeRESERVED_CHECK_KEYThe key names a check the platform implements; a check you report needs a key of its own400
In the body as
error.reasonRESERVED_NAMESPACEThe name is reserved — for the platform, or for the organization that owns the domain the message names403
In the body as
error.reasonRESERVED_PERMISSIONThe role grants a permission only a built-in role can carry422
In the body as
error.reasonNo operation lists it: it answers only the callers named above.
REVIEWER_CANNOT_VIEWThe reviewer cannot read this merge request422
In the body as
error.reasonROLE_BASE_OWNERA custom role is based on Guest, Reporter, Developer or Maintainer, never Owner422
In the body as
error.reasonNo operation lists it: it answers only the callers named above.
ROLE_IN_USEGrants or limits still use this role; change or revoke them first409
In the body as
error.reasonROLE_SLUG_TAKENThe organization already has a role with this slug409
In the body as
error.reasonRULE_ALREADY_STRENGTHENEDThis group or repository already strengthens that rule; change that rule instead409
In the body as
error.reasonSELF_APPROVAL_FORBIDDENThe environment does not let the person who started a run approve it403
In the body as
error.reasonSERVICE_ACCOUNT_CANNOT_BE_OWNERA service account can hold Maintainer at most422
In the body as
error.reasonSERVICE_ACCOUNT_OUTSIDE_HOMEA service account can be given access only at its own group or repository, or beneath it422
In the body as
error.reasonSERVICE_REQUIRES_PATHSA service that is not external must claim at least one repository path400
In the body as
error.reasonSESSION_ENDEDThe AI session has ended409Agents only
In the body as
error.reasonNo operation lists it: it answers only the callers named above.
SESSION_REQUIREDThis is done from a signed-in browser session, never with an access token403
START_BRANCH_NOT_FOUNDThe branch a new branch was to start from does not exist404
In the body as
error.reasonviolations[].codeTEAM_ROSTER_MANAGED_BY_IDPThe team's members are kept by the identity provider; change the group there409
In the body as
error.reasonTEAM_SLUG_TAKENThe organization already has a team with this slug409
In the body as
error.reasonTOO_MANY_REQUESTSA quota, a rate limit or a transfer budget is spent. When the response carries `Retry-After`, retry after that many seconds429Retryable
In the body as
error.codeReturned by 102 operations — each operation's page lists it under its status.
UNAUTHORIZEDNo credential was sent, or the one sent is invalid, expired or revoked401
In the body as
error.codeReturned by 700 operations — each operation's page lists it under its status.
UNKNOWN_CHECKThe key names no check the platform implements400
In the body as
error.reasonUNPROCESSABLE_ENTITYThe request is well-formed but asks for something the resource's rules do not allow; `reason` says which422
In the body as
error.code- PATCH/access/grants/{grant_id}
- POST/admin/provider-submissions/{submission_id}/approve
- PATCH/approval-rules/{rule_id}
- POST/groups/{group_id}/access/grants
- POST/groups/{group_id}/ai-org
- POST/groups/{group_id}/ai-org/consent
- POST/groups/{group_id}/ai-org/profile-drafts
- PUT/groups/{group_id}/ai-org/revisions/draft
- POST/groups/{group_id}/ai-org/revisions/draft/publish
- PUT/groups/{group_id}/approval-policy
- POST/groups/{group_id}/approval-rules
- POST/groups/{group_id}/branch-rules
- PATCH/groups/{group_id}/branch-rules/{branch_rule_id}
- POST/groups/{group_id}/provider-connections
- PUT/groups/{group_id}/provider-connections/{connection_id}
- PATCH/groups/{group_id}/push-rules
- POST/groups/{group_id}/roles
- POST/groups/{group_id}/teams
- POST/publishers/{publisher_id}/verification-challenge/verify
- POST/repositories/{repo_id}/access/grants
- PUT/repositories/{repo_id}/access/inheritance
- PUT/repositories/{repo_id}/approval-policy
- POST/repositories/{repo_id}/approval-rules
- POST/repositories/{repo_id}/branch-rules
- PATCH/repositories/{repo_id}/branch-rules/{branch_rule_id}
- POST/repositories/{repo_id}/branches
- POST/repositories/{repo_id}/commits
- POST/repositories/{repo_id}/merge-requests/{mr_id}/conflicts/resolve
- POST/repositories/{repo_id}/merge-requests/{mr_id}/reviewers
- POST/repositories/{repo_id}/provider-connections
- PUT/repositories/{repo_id}/provider-connections/{connection_id}
- PATCH/repositories/{repo_id}/push-rules
- PATCH/roles/{role_id}
- PUT/teams/{team_id}/idp-link
- PUT/teams/{team_id}/members/{user_id}
UNRESOLVEDA conflicted file has no resolution in the request422
In the body as
error.reasonviolations[].codeUNSUPPORTED_CONFLICTThe conflict is of a kind that cannot be resolved in the browser422
In the body as
error.reasonviolations[].codeUNSUPPORTED_ENTRYThe entry is a symbolic link, a submodule or a directory, which a commit written in the browser does not change422
In the body as
error.reasonviolations[].codeUSE_ACCESS_APIThe person holds a custom role here; change it through access grants409
USE_SERVICE_ACCOUNT_APIThis is a service account's access at its own home; change it on the service account409
In the body as
error.reasonVALIDATION_ERRORA value is outside what the operation accepts; the message says which400
In the body as
error.reason- PATCH/catalog/services/{service_id}
- GET/groups/{group_id}/catalog/deployments
- POST/groups/{group_id}/catalog/services
- GET/repositories/{repo_id}/catalog/resolve
- POST/repositories/{repo_id}/pipeline-runs
- POST/repositories/{repo_id}/pipeline-runs/{pipeline_run_id}/approve
- POST/repositories/{repo_id}/pipeline-runs/{pipeline_run_id}/retry
watch_capacity_reachedThe server is at its live-update capacity. Retry after `Retry-After` seconds, or read the resource directly in the meantime503Retryable
WOULD_LOCK_OUT_ACTORThe change would take away your own ability to undo it; ask an organization owner409
In the body as
error.reasonWOULD_WEAKEN_ENFORCED_RULEThe setting would be weaker than a rule enforced above it allows422
In the body as
error.reason- PATCH/approval-rules/{rule_id}
- PUT/groups/{group_id}/approval-policy
- POST/groups/{group_id}/approval-rules
- POST/groups/{group_id}/branch-rules
- PATCH/groups/{group_id}/branch-rules/{branch_rule_id}
- PATCH/groups/{group_id}/push-rules
- PUT/repositories/{repo_id}/approval-policy
- POST/repositories/{repo_id}/approval-rules
- POST/repositories/{repo_id}/branch-rules
- PATCH/repositories/{repo_id}/branch-rules/{branch_rule_id}
- PATCH/repositories/{repo_id}/push-rules