# Errors

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

Product: Clad API
Source: https://docs.useclad.ai/api/errors

---

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:

```graphql
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.