Errors

In-band result errors, top-level GraphQL errors, and the canonical error-code taxonomy.

The API uses two error channels:

1. In-band result errors (expected failures). Mutations return a result union whose error member is non-null on failure. Always select error and check it:

mutation {
  createIssue(input: { subject: "", body: "" }) {
    issue { id }
    error { code message retryable fields { path message } }
  }
}

2. Top-level GraphQL errors (request-shape / auth failures). Malformed queries, missing auth, and rate limits appear in the response's top-level errors array. Each carries extensions.code, extensions.retryable, and extensions.requestId (also returned as the x-request-id response header — include it in support requests).

Error codes:

Code	Meaning	Retryable
`VALIDATION`	Bad input; see `fields` for per-field detail	No
`UNAUTHENTICATED`	Missing, invalid, revoked, or expired key	No
`FORBIDDEN`	Key lacks the required scope	No
`NOT_FOUND`	Object does not exist (or not in your org)	No
`CONFLICT`	Uniqueness/state conflict (e.g. duplicate slug)	No
`RATE_LIMITED`	Too many requests	Yes
`DEPENDENCY_FAILED`	A downstream dependency failed	Yes
`INTERNAL`	Unexpected server error	Yes

Internal errors never include internal detail on the wire — use the requestId when contacting support.