Error Codes

Every error returned by the REST API and the MCP server uses a uniform envelope:

{
  "error": {
    "code": "TENANT_MISMATCH",
    "message": "The requested resource does not belong to the team this API token is scoped to.",
    "docs_url": "https://docs.example.test/api/v1/errors#tenant-mismatch",
    "remediation": "Use a token minted for the correct team, or switch the account's current team before minting.",
    "request_id": "00-abc...",
    "context": { "project_id": "7d1f..." }
  }
}

Fields:

• code: a stable string identifier. Pattern-match on this.
• message: a human-readable summary, free to change between releases.
• docs_url: an anchor into this page.
• remediation: a one-sentence hint for self-correction.
• request_id: a trace identifier. Share it with your administrator when reporting a problem.
• fields: only present on VALIDATION_FAILED. Maps each offending key to a list of rule-failure messages.
• context: only present when the thrower supplied extra context, such as required_ability on TOKEN_MISSING_ABILITY or project_id on TENANT_MISMATCH.

ValidationCopy Anchor Link

VALIDATION_FAILEDCopy Anchor Link

• HTTP status: 422
• When: The request body failed a validation rule, or an action refused the request on a rule of the domain: a role code already taken, a team you cannot rename, a token that would outrank its minter.
• Remediation: Inspect error.fields when present; otherwise the message says which rule refused.

Authentication and authorizationCopy Anchor Link

AUTHENTICATION_REQUIREDCopy Anchor Link

• HTTP status: 401
• When: No Authorization: Bearer zg_live_... header is present, the token has been revoked, or it was minted for another environment.
• Remediation: Mint a fresh token under Account Settings → API Tokens and retry.

TOKEN_MISSING_ABILITYCopy Anchor Link

• HTTP status: 403
• When: The token is valid but does not carry the ability required for this endpoint or tool.
• Context: required_ability, the exact ability string to grant.
• Remediation: Mint a replacement token that includes the listed ability, or ask the team owner to grant it to your role.

FORBIDDENCopy Anchor Link

• HTTP status: 403
• When: The token carries the right ability and can see the resource, but its holder may not change it. Today this applies to webhook endpoints: only the member who registered an endpoint, or the team owner, may rotate, test, pause or delete it.
• Remediation: Ask the endpoint's creator or the team owner to make the change, or mint the token as that member.

TENANT_MISMATCHCopy Anchor Link

• HTTP status: 404
• When: The token's scope:team:<uuid> does not match the team that owns the resource, the token is missing scope:team:<uuid> entirely, or scope:project:<uuid> excludes the project.
• Remediation: Use a token minted for the correct team or project. The response is 404 rather than 403 so existence outside the scope cannot be inferred.

RESOURCE_NOT_FOUNDCopy Anchor Link

• HTTP status: 404
• When: The id in the path does not exist, is malformed, or is hidden by scope; or a body named a team, a target or a user that is not yours.
• Remediation: Verify the id. The resource may have been deleted, never existed, or sit outside the token's scope.

Lifecycle refusalsCopy Anchor Link

These codes belong to the planning, build, release and maintenance phases and are published here so a client can prepare for them; the endpoints that raise them land with their phases.

APPROVAL_REQUIREDCopy Anchor Link

• HTTP status: 422
• When: The change needs an approval that has not been given yet.
• Remediation: Submit the artefact for review and wait for the decision, or ask an approver named in error.context to decide it.

BASELINE_LOCKEDCopy Anchor Link

• HTTP status: 422
• When: The artefact is frozen in a baseline and can only change through an approved change request.
• Remediation: Open a change request against the baseline named in error.context; once it is approved the artefact can be edited again.

TRANSITION_NOT_ALLOWEDCopy Anchor Link

• HTTP status: 422
• When: The item cannot move from its current status to the requested one.
• Remediation: Read error.context.allowed for the statuses the item may move to.

DEFINITION_INCOMPLETECopy Anchor Link

• HTTP status: 422
• When: The item's definition checklist has unticked required entries.
• Remediation: Tick the entries listed in error.context.missing, then retry the transition.

SPRINT_ALREADY_ACTIVECopy Anchor Link

• HTTP status: 422
• When: The project already has an active sprint.
• Remediation: Close the active sprint, or move the items into it instead.

ENVIRONMENT_PROTECTEDCopy Anchor Link

• HTTP status: 422
• When: Deployments into this environment need a promotion approval first.
• Remediation: Request a promotion; the deployment runs once a release manager approves it.

AI_BUDGET_EXHAUSTEDCopy Anchor Link

• HTTP status: 422
• When: The team's AI budget for this month is spent.
• Remediation: Ask a team admin to raise the month's budget, or wait for the next month.

INTEGRATION_NOT_CONNECTEDCopy Anchor Link

• HTTP status: 422
• When: The integration this call relies on is not connected for the team or project.
• Remediation: Connect the integration from the settings, then retry.

LIMIT_REACHEDCopy Anchor Link

• HTTP status: 422
• When: A limit on the project or team refused the request.
• Remediation: Read the message for the limit that refused the request and reduce the request, or ask a team admin to raise it.

IdempotencyCopy Anchor Link

IDEMPOTENCY_KEY_MISSINGCopy Anchor Link

• HTTP status: 400
• When: A mutating endpoint (POST, PATCH, PUT, DELETE) was called without an Idempotency-Key header.
• Remediation: Generate a fresh UUID, send it as Idempotency-Key, retry.

IDEMPOTENCY_KEY_REUSEDCopy Anchor Link

• HTTP status: 409
• When: The same Idempotency-Key was used previously with a different request body.
• Remediation: Use a fresh key per distinct operation.

IDEMPOTENCY_REPLAY_IN_PROGRESSCopy Anchor Link

• HTTP status: 425
• When: A prior request with the same key is still running; the server is serialising concurrent retries.
• Remediation: Wait briefly and retry.

Request shapeCopy Anchor Link

METHOD_NOT_ALLOWEDCopy Anchor Link

• HTTP status: 405
• When: The path exists but does not accept the verb you used.
• Remediation: Check the endpoint reference for the verbs the path accepts; the response carries an Allow header listing them.

ThrottlingCopy Anchor Link

RATE_LIMITEDCopy Anchor Link

• HTTP status: 429
• When: The token (or IP for unauthenticated routes) exceeded its bucket. See rate limiting.
• Remediation: Back off per the Retry-After header.

WebhooksCopy Anchor Link

WEBHOOK_ENDPOINT_UNREACHABLECopy Anchor Link

• HTTP status: 502
• When: A synchronous call to a webhook endpoint could not reach the target.
• Remediation: Verify the endpoint is HTTPS-reachable from the public internet. Queued deliveries are retried on the backoff ladder before dead-lettering.

ServerCopy Anchor Link

INTERNAL_SERVER_ERRORCopy Anchor Link

• HTTP status: 500
• When: An unexpected server-side failure.
• Remediation: Capture error.request_id and report it. Every 5xx is recorded on the server side.