> For the complete documentation index, see [llms.txt](https://docs.durohub.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.durohub.com/advanced-topics/error-handling.md).

# Error Handling

Learn how to handle errors and edge cases in the Duro API.

### Error Types

The API returns different types of errors:

* Validation errors
* Authentication errors (see [Authentication Errors](#authentication-errors) — these use a different envelope)
* Authorization errors
* Entitlement (subscription plan) errors
* Rate limiting errors
* Server errors

### Error Format

Errors arrive in the standard GraphQL `errors` array. `extensions.code` is the stable, programmatic key — branch on it rather than on `message`, which may be reworded.

```json
{
  "errors": [
    {
      "message": "Unauthorized",
      "path": ["user"],
      "extensions": {
        "code": "UNAUTHENTICATED",
        "originalError": { "message": "Unauthorized", "statusCode": 401 },
        "service": "foundation"
      }
    }
  ]
}
```

There are two shapes to be aware of, and `code` is the only key present in both:

* **Framework errors** — authentication failures raised before your operation runs (`UNAUTHENTICATED`), and the exports service's `FORBIDDEN`. The status is nested under `extensions.originalError.statusCode`, as above.
* **Domain errors** — business-rule violations raised by the operation itself, and most authorization failures. Every code documented on this page is one of these. They usually carry `statusCode` directly on `extensions`, with no `originalError`; a few carry only `code`, so branch on `code` alone:

```json
{
  "errors": [
    {
      "message": "Seat limit reached (25/25). Upgrade your plan or remove a member to add more.",
      "path": ["teams", "addMembers"],
      "extensions": {
        "code": "SEAT_LIMIT_REACHED",
        "statusCode": 403,
        "service": "foundation"
      }
    }
  ]
}
```

`service` names the subgraph that raised the error. A few domain errors carry extra keys; those are called out alongside the code below.

### Authorization Errors

Authorization failures are domain errors. A failed permission check returns `PERMISSION_NOT_FOUND` (403), `NO_ROLE_ASSIGNED` (403), or `MISSING_CONTEXT` (400); a request for a resource in another organization or library returns `UNAUTHORIZED_RESOURCE_ACCESS` (403) or one of its resource-specific variants. The sourcing and exports services return `FORBIDDEN` (403) instead: sourcing's carries the status in `extensions.statusCode`, and exports' in `extensions.originalError.statusCode` (a framework error). One sourcing operation, [`vendorSearch.buildFilterWithAI`](https://docs.durohub.com/core-concepts/sourcing.md#building-vendor-filters-with-ai), returns the codes above rather than `FORBIDDEN`. Neither status is the HTTP status, so branch on `code`. See [Permission errors](https://docs.durohub.com/advanced-topics/rbac.md#permission-errors) and [Tenant Scoping](https://docs.durohub.com/advanced-topics/rbac.md#tenant-scoping).

```json
{
  "errors": [
    {
      "message": "Required permission \"components.update\" not found in your role",
      "path": ["component", "update"],
      "extensions": {
        "code": "PERMISSION_NOT_FOUND",
        "statusCode": 403,
        "service": "foundation"
      }
    }
  ]
}
```

### Rate Limiting Errors

When an operation's budget is empty, the API refuses the whole request with HTTP `429 Too Many Requests` before running any of it. The body names the budget and how many seconds to wait, and the `Retry-After` header carries the same wait:

```http
HTTP/1.1 429 Too Many Requests
Retry-After: 2
RateLimit-Policy: "bulk-write";q=20;w=60
RateLimit: "bulk-write";r=0;t=59
```

```json
{
  "errors": [
    {
      "message": "Rate limit reached for bulk-write.",
      "extensions": {
        "code": "RATE_LIMITED",
        "budget": "bulk-write",
        "retryAfter": 2
      }
    }
  ]
}
```

This refusal comes from in front of the API rather than from a subgraph, so it carries no `path`, `service` or `statusCode`. Wait `extensions.retryAfter` seconds and send the request again unchanged: nothing in it ran. See [Rate Limits](https://docs.durohub.com/rate-limits/rate-limits.md) for how budgets work, and [Handling 429s](https://docs.durohub.com/rate-limits/handling-429s.md) for a retry helper.

### Authentication Errors

Errors from the `/auth/*` signup and email-verification endpoints do **not** use the GraphQL envelope. They are REST endpoints, and they return a flat JSON body:

```json
{
  "code": "AUTH_TOKEN_INVALID",
  "message": "This link is invalid or has expired"
}
```

The `code` is stable; the `message` is copy and may be reworded. Branch on `code`.

| Code                    | Status | Meaning                                                                                                                                                                                                                                                                                                                                                                    |
| ----------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AUTH_ORIGIN_REJECTED`  | 403    | Missing or non-allowlisted `Origin` header. Browsers send it automatically; `curl` does not                                                                                                                                                                                                                                                                                |
| `AUTH_TOKEN_INVALID`    | 400    | A verification token that is unknown, expired, or already used                                                                                                                                                                                                                                                                                                             |
| `AUTH_RATE_LIMITED`     | 429    | Far past the route's limit. The body carries `retryAfter` (seconds) and the response a matching `Retry-After` header. See [Sign-in is limited differently](https://docs.durohub.com/rate-limits/rate-limits.md#sign-in-is-limited-differently); the SAML sign-in limits are on [Enterprise SSO](https://docs.durohub.com/account-management/enterprise-sso.md#rate-limits) |
| `AUTH_REQUEST_REJECTED` | 4xx    | Malformed request — a missing field, a bad email shape, or a rejected password                                                                                                                                                                                                                                                                                             |
| `AUTH_UNAVAILABLE`      | 503    | Temporary failure. Retry                                                                                                                                                                                                                                                                                                                                                   |

Some codes deliberately cover more than one situation, so that the error surface cannot be used to work out who has a Duro account. See [Creating an Account](https://docs.durohub.com/account-management/creating-an-account.md).

### Access Errors

Authenticating identifies *who* you are. A separate check decides whether that identity may use Duro at all — see [`user.me.permitted`](https://docs.durohub.com/getting-started/current-user.md#fields). A valid token whose identity is not permitted is refused at every data operation with `ACCESS_NOT_PERMITTED`. The token itself is fine; the account is not yet allowed in.

| Code                   | Status | Meaning                                                                                                                                                                                                                         | How to resolve                                                                                                                                                                                             |
| ---------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ACCESS_NOT_PERMITTED` | 403    | The identity is authenticated but not permitted: it is archived, or it has no organization membership, no pending invitation, no allowlisted email or domain, and no pending organization-creation grant. Nothing was returned. | Query `user.me { permitted }` to confirm. The account needs to be invited to an organization, or its email or domain approved by Duro. Once it is permitted the same request succeeds with the same token. |

```json
{
  "errors": [
    {
      "message": "Your access to Duro is not yet enabled.",
      "path": ["component", "list"],
      "extensions": {
        "code": "ACCESS_NOT_PERMITTED",
        "statusCode": 403,
        "service": "foundation"
      }
    }
  ]
}
```

{% hint style="info" %}
`ACCESS_NOT_PERMITTED` is distinct from the [authorization errors](#authorization-errors). `PERMISSION_NOT_FOUND` and its siblings mean the identity is in Duro but lacks permission for a specific operation or resource — see [Role-Based Access Control](https://docs.durohub.com/advanced-topics/rbac.md). `ACCESS_NOT_PERMITTED` means the identity is not allowed into Duro at all. `user.me` itself always resolves, so a client can read `permitted` and show a clear message instead of retrying.
{% endhint %}

### Validation Errors

Validation errors are returned when a mutation violates a business rule. The `extensions.code` identifies the specific rule so you can handle it programmatically.

| Code                          | Operation        | Meaning                                                                                                                                                                                                                                            |
| ----------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `NRM_NOT_ALLOWED_ON_OBSOLETE` | Component update | A component cannot be marked Not Revision Managed (NRM) while it is Obsolete. Change the status away from Obsolete before enabling NRM. See [Not Revision Managed](https://docs.durohub.com/core-concepts/components.md#not-revision-managed-nrm). |

```json
// Marking an Obsolete component as NRM
{
  "errors": [
    {
      "message": "Not Revision Managed and Obsolete cannot be combined. Turn off Not Revision Managed before obsoleting this component.",
      "path": ["component", "update"],
      "extensions": {
        "code": "NRM_NOT_ALLOWED_ON_OBSOLETE",
        "statusCode": 400
      }
    }
  ]
}
```

### Item Write Errors

`item.create` and `item.update` write a component together with its BOM children and its documents in a single transaction — see [Item Mutations](https://docs.durohub.com/core-concepts/components.md#item-mutations-bom-and-documents-in-one-call). Because the whole call is one unit of work, an oversized request is refused up front rather than partially applied.

| Code                   | Operation                    | Meaning                                                                                                                       |
| ---------------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `ITEM_WRITE_TOO_LARGE` | `item.create`, `item.update` | The request exceeds one of the write limits below. The check runs before any work starts, so nothing was written. HTTP `413`. |

The limits (per call unless stated):

| Limit                                                         | Maximum |
| ------------------------------------------------------------- | ------- |
| Components in one `inputs` array                              | 10      |
| `children` on one component                                   | 20      |
| `children` summed across the call                             | 200     |
| `documents` on one component                                  | 20      |
| `documents` summed across the call                            | 20      |
| `documentComponentIds` on one component                       | 20      |
| `removeDocumentLinkIds` on one component (`item.update` only) | 20      |

The `message` names the limit that was hit:

```json
{
  "errors": [
    {
      "message": "This call exceeds a write limit: 25 children on component \"ASM-0042\" (maximum 20)",
      "path": ["item", "update"],
      "extensions": {
        "code": "ITEM_WRITE_TOO_LARGE",
        "statusCode": 413
      }
    }
  ]
}
```

**How to resolve:** split the work into several calls, one per component rather than a large batch, and move a component's documents into a follow-up `item.update` if the component alone is still too large. Do **not** split a single component's `children` across calls — the list is desired-state, so a partial list unlinks the children left out of it. A parent with more than 20 children cannot be published through `item.*` at all: create it with no `children`, then send the full BOM through `assemblyMutation.updateBOM`, which has no such cap. Retrying the same request unchanged will not succeed.

### Document Link History Errors

Adding or removing a document link on its own — outside a change order and outside an `item.*` call — is a single transaction: the link write and the history row that records it either both land or neither does.

| Code                            | Operation                             | Meaning                                                                                                                               |
| ------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `DOCUMENT_HISTORY_WRITE_FAILED` | standalone document link add / remove | The link change could not be recorded in the component's history, so the whole save was rolled back. Nothing was written. HTTP `500`. |

```json
{
  "errors": [
    {
      "message": "Failed to record document link history for component \"PRT-0042\"",
      "path": ["documentLink", "create"],
      "extensions": {
        "code": "DOCUMENT_HISTORY_WRITE_FAILED",
        "statusCode": 500,
        "service": "foundation"
      }
    }
  ]
}
```

**How to resolve:** the failure is transient on the server side, not a problem with the request. Retry the same call. Because the save rolled back, retrying cannot produce a duplicate link or a duplicate history row. If it persists, contact support with the component and document IDs.

### Change Order Template Errors

Uploading a workflow template (`changeOrders.createTemplate` / `changeOrders.updateTemplate`) runs a set of checks on the YAML before it is stored. Participant checks (`TEMPLATE_PARTICIPANT_*`) and [change order type checks](https://docs.durohub.com/library-configuration/change-order-workflow-reference.md#rules-and-validation) run for every version. Structural validation against the versioned JSON Schema runs only for versions listed as enforced in the [version manifest](https://docs.durohub.com/library-configuration/change-order-workflow-reference.md#schema-versions-and-the-manifest), which today is `1.2`.

#### `TEMPLATE_CONFIG_INVALID`

Returned when a `1.2` template fails validation against [`schema-1.2.json`](https://durohub.com/configs/change-orders/schema-1.2.json). The check runs on template create and update, and when a library's built-in templates are seeded. `1.0` and `1.1` templates are not validated against their schema, so they never return this code.

HTTP `400`. The message gives the location of the problem as a JSON Pointer into the config, then the reason:

```json
{
  "errors": [
    {
      "message": "Template config is invalid at /stages/open/0/types: Invalid type: expected array.",
      "path": ["changeOrders", "createTemplate"],
      "extensions": {
        "code": "TEMPLATE_CONFIG_INVALID",
        "statusCode": 400
      }
    }
  ]
}
```

The reason is one of:

| Reason                                        | Meaning                                                                                  |
| --------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `Missing required field: <name>`              | A required property is absent, for example a stage without `name`.                       |
| `Invalid type: expected <type>`               | A value has the wrong type, such as a string where an array belongs.                     |
| `Invalid format: <detail>`                    | A string does not match its pattern, such as a reviewer ID that is not a lowercase UUID. |
| `Invalid value: must be one of [<values>]`    | A value is outside its allowed set, such as an unknown approval type.                    |
| `Field is not allowed at this schema version` | The key exists in the format but not at the version the template declares.               |

**How to resolve:**

* Follow the pointer in the message to the key (`/stages/open/0/types` above is the `types` of the first open stage) and fix it in your YAML.
* Validate locally against `schema-1.2.json` before uploading. The [Workflow YAML Reference](https://docs.durohub.com/library-configuration/change-order-workflow-reference.md#json-schema-validation) shows how to wire the schema into your editor.
* Unknown keys are **not** a cause of this error; the schemas allow them.
* A template cannot be moved back from `1.2` to an earlier version to avoid validation; that is rejected with `CANNOT_DOWNGRADE_SCHEMA_VERSION`.

### Change Order Type Errors

Selecting a change order [type](https://docs.durohub.com/core-concepts/change-orders.md#change-order-types) can produce validation errors when the requested type is not permitted, or when a `DCO` (Documentation Change Order) is asked to do something its revision-freeze forbids.

#### `CO_TYPE_NOT_ALLOWED`

Returned when a change order is given a `coType` that the chosen template does not allow. A template's allowed types are declared in its `co_types` list (schema version `1.1`). The resolved type — whether passed explicitly in the input, taken from the template's `defaultCoType`, or defaulted to `ECO` — must be a member of that list.

This applies both at creation (`changeOrders.create`) and when switching a draft change order's type or template with `changeOrders.submitDraft` (`coType` / `configId`) — see [Switching Type and Template in Draft](https://docs.durohub.com/core-concepts/change-orders.md#switching-type-and-template-in-draft). When both fields are passed to `submitDraft`, the type is validated against the **new** template.

```json
{
  "errors": [
    {
      "message": "Change order type \"MCO\" is not allowed by this template. Allowed types: [ECO, DCO].",
      "path": ["changeOrders", "create"],
      "extensions": {
        "code": "CO_TYPE_NOT_ALLOWED",
        "statusCode": 400
      }
    }
  ]
}
```

**How to resolve:**

* Query the template's allowed types before creating and pass a `coType` that is a member of `coTypes` (or omit `coType` to fall back to `defaultCoType`):

  ```graphql
  query {
    changeOrders {
      getTemplates { id name coTypes defaultCoType }
    }
  }
  ```
* Legacy (`1.0`) templates return `null` for `coTypes` and allow only `ECO`. To offer additional types, migrate the template to `version: "1.2"` — see the [Workflow YAML Reference](https://docs.durohub.com/library-configuration/change-order-workflow-reference.md#change-order-types).

{% hint style="info" %}
This check is enforced atomically against the template, so a concurrent edit that removes a type in the same instant cannot let a disallowed type slip through — you will consistently get `CO_TYPE_NOT_ALLOWED` rather than a change order that outlives its template's rules.
{% endhint %}

#### `DCO_STATUS_CHANGE_NOT_ALLOWED` / `DCO_REVISION_CHANGE_NOT_ALLOWED`

A change order of type `DCO` is **revision-frozen**: it never bumps a component's revision and cannot change a component's `status` or `revision`. These codes are raised whenever a DCO would result in such a change. If the change genuinely needs to alter a component's status or revision, use a non-`DCO` type. See [Change Order Types](https://docs.durohub.com/core-concepts/change-orders.md#change-order-types).

They surface synchronously in two situations:

* **Proposed change.** Proposing a status change or a revision change directly on a DCO item is rejected.
* **Baseline drift at submit.** The built-in [DCO baseline validation](https://docs.durohub.com/library-configuration/change-order-validations.md#dco-baseline-freeze) blocks the change order when any item's live `status` or `revision` has drifted from its last-released baseline — for example because a concurrent change order released a new revision of that item after it was added to the DCO. The release that runs after a DCO closes re-checks the baseline too. That check runs in a background release job, not in your API call, so its failures never come back as a GraphQL error: if drift is detected then — with these codes, or `DCO_LEGACY_RELEASE_UNKNOWN` when a DCO item has no releasable baseline — no items are released and the change order stays `CLOSED` but unreleased.

### Change Order Item Errors

`changeOrders.addItems` accepts at most **1,000** items per call. The check runs before anything else, so a refused call adds nothing.

| Code             | Status | Meaning                                                                                                                                                                       |
| ---------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `TOO_MANY_ITEMS` | 400    | `input.items` has more than 1,000 entries. The message names both numbers, for example "Add at most 1,000 items per call; this call has 1,250. Split the items across calls." |

**How to resolve:** split the list into calls of 1,000 or fewer (exactly 1,000 passes). Each call is one charge against the `co-items` [rate-limit budget](https://docs.durohub.com/rate-limits/budgets.md) however many items it carries, so chunking at the cap is also the cheapest way to add a large list. `removeItems` has no cap. See [Adding Items to a Change Order](https://docs.durohub.com/core-concepts/change-orders.md#adding-items-to-a-change-order).

### Change Order Filter Errors

Each text condition on `changeOrders.get`'s `advancedFilter` applies a fixed set of operators. A condition sent with any other operator is refused: the request fails and no change orders are returned.

| Code                          | Status | Meaning                                                                                                                                                                                                                                                 |
| ----------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `UNSUPPORTED_FILTER_OPERATOR` | 400    | A condition used an operator its field does not apply. The message names the field, the operators refused and the ones supported, for example "Filter field "nameOrEco" does not support the operator(s) like. Supported: eq, neq, in, notIn, contains" |

**How to resolve:** use one of the operators the message lists. The operators each condition applies are in [Filter Options](https://docs.durohub.com/core-concepts/change-orders.md#filter-options).

{% hint style="info" %}
Before this error was added for every text condition, an operator a condition did not apply was ignored, so a filter holding only that condition returned every change order. If an integration relied on such a filter returning results, it was not filtering.
{% endhint %}

### Change Order Content Errors

Custom content fields on a change order — the fields its template defines under `contents` — are validated against their field definition whenever a value is written. This applies to [`changeOrders.setContentValue`](https://docs.durohub.com/core-concepts/change-orders.md#setting-custom-field-values) (`input: { values: [...] }`) and to content updates passed in `changeOrders.submitDraft(id, input)`. All five codes return HTTP `400`.

| Code                          | Field types                                            | Meaning                                                                                                                                                                                                                                                                                                                             |
| ----------------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CONTENT_TOO_MANY_VALUES`     | text, long text, number, currency, date, single-select | More than one value was sent for a field that holds a single value, for example `values: ["a", "b"]`. Only multi-select fields accept several values.                                                                                                                                                                               |
| `CONTENT_VALUE_NOT_AN_OPTION` | single-select, multi-select                            | A value is not one of the field's configured options. Matching is exact — case- and whitespace-sensitive — and is against option **values**, not labels. A field whose option list is empty accepts any value.                                                                                                                      |
| `CONTENT_VALUE_NOT_A_NUMBER`  | number, currency                                       | After trimming, the value is not a finite decimal. Accepted: `"12"`, `"-3"`, `"1.5"`, `".5"`, `"1e-7"`. Rejected: `"1,234"`, `"+5"`, `"0x10"`, `""`. The trimmed string is what gets stored.                                                                                                                                        |
| `CONTENT_INVALID_DATE`        | date                                                   | The trimmed value is empty or cannot be parsed as a date, for example `"not-a-date"`. Parsing follows JavaScript date parsing rather than a strict ISO 8601 grammar, so some non-ISO inputs are accepted even though the message refers to ISO format. Accepted values are stored normalized to an ISO timestamp (`toISOString()`). |
| `CONTENT_DATE_ROLLED_OVER`    | date                                                   | The value parsed, but its UTC year, month, or day differs from the `YYYY-MM-DD` prefix it begins with — typically a calendar date that does not exist, such as `"2026-02-30"`. A timestamp with a UTC offset can also fail this check when its UTC calendar date differs from the prefix.                                           |

Every one of these carries two extra keys on `extensions`: `field`, the label of the content field, and `value`, the rejected input. `CONTENT_VALUE_NOT_AN_OPTION` also carries `options`, the full list of the field's configured option values.

```json
// values: ["Low", "High"] sent for a single-select field
{
  "errors": [
    {
      "message": "Field \"Change Category\" accepts a single value but received 2.",
      "path": ["changeOrders", "setContentValue"],
      "extensions": {
        "code": "CONTENT_TOO_MANY_VALUES",
        "statusCode": 400,
        "field": "Change Category",
        "value": "Low, High"
      }
    }
  ]
}
```

```json
// A value that is not one of the field's options
{
  "errors": [
    {
      "message": "Field \"Change Category\" must be one of: design, process, documentation.",
      "path": ["changeOrders", "setContentValue"],
      "extensions": {
        "code": "CONTENT_VALUE_NOT_AN_OPTION",
        "statusCode": 400,
        "field": "Change Category",
        "value": "Design",
        "options": ["design", "process", "documentation"]
      }
    }
  ]
}
```

A few details about what is reported:

* `extensions.value` is capped at 100 Unicode code points; longer input is cut there and suffixed with `…`. For `CONTENT_TOO_MANY_VALUES` the offending values are joined with `", "` before the cap is applied.
* The option list in the `message` is truncated separately from `extensions.options`, which is always complete. Read `options` rather than parsing the message.
* As with the other domain errors on this page, `statusCode` on `extensions` is informational: it is the code's classification, not a verified HTTP response status.

**What is validated and what is saved:**

* Only **changed** values are validated. For single-value fields the incoming array is compared to the stored one in order; for multi-select fields the two are compared as multisets, so duplicates count. Re-sending a field's current value never fails validation, even if that value would not pass today's rules.
* For multi-select fields, only **newly added** occurrences are checked against the options. Existing values that are no longer options are preserved as long as they are re-sent. Reordering a multi-select field's values is accepted and the new order is stored.
* `values: []` clears a field.
* In `submitDraft`, invalid content aborts the whole mutation: nothing from that submission is saved.

{% hint style="info" %}
Before this validation existed, an unparseable or rolled-over date was rejected with the generic `BAD_REQUEST` code. Branch on `CONTENT_INVALID_DATE` and `CONTENT_DATE_ROLLED_OVER` instead.
{% endhint %}

### Required Approver Errors

From template `version: '1.2'`, a stage reviewer can be a [required approver](https://docs.durohub.com/library-configuration/change-order-workflow-reference.md#required-approvers). These errors protect that guarantee. All three return HTTP `400`.

#### `INLINE_CONFIG_REVIEWER_OBJECTS_UNSUPPORTED`

Returned when `changeOrders.create` is called with an **inline** `config` (a workflow definition passed directly in the input rather than a saved template) in which a stage's `reviewers.users` contains reviewer **objects**, such as `{ id: "<uuid>", isRequiredToApprove: true }`. Inline configurations only accept reviewers as **UUID strings**. Required approvers can only come from a saved template.

```json
{
  "errors": [
    {
      "message": "Stage \"Engineering Review\": reviewers on an inline change order config must be user ID strings. Required approvers come from a change order template, so create the change order from one instead.",
      "path": ["changeOrders", "create"],
      "extensions": {
        "code": "INLINE_CONFIG_REVIEWER_OBJECTS_UNSUPPORTED",
        "statusCode": 400
      }
    }
  ]
}
```

**How to resolve:**

* If you do not need required approvers, pass the reviewers as plain UUID strings in the inline `config`:

  ```yaml
  reviewers:
    users:
      - "550e8400-e29b-41d4-a716-446655440001"
      - "550e8400-e29b-41d4-a716-446655440002"
  ```
* If you need required approvers, save the configuration as a `1.2` template with `changeOrders.createTemplate` and create the change order from that template instead. See [Change Order Workflows](https://docs.durohub.com/library-configuration/change-order-workflows.md#required-approvers) and [Getting Available Templates](https://docs.durohub.com/core-concepts/change-orders.md#getting-available-templates).

#### `REQUIRED_APPROVER_UNRESOLVABLE`

Returned when a change order is created from a template, or a draft change order is switched to one, and a required approver on the template can no longer be added as a reviewer in the library, for example because they have left the organization. Ordinary reviewers in that situation are skipped with an activity-feed warning; a required approver is not, because skipping them would let the stage pass without them. Nothing is created.

```json
{
  "errors": [
    {
      "message": "Stage \"Quality Review\" requires approval from user 123e4567-e89b-12d3-a456-426614174004, who can't be added as a reviewer in this library. Someone who can manage change order templates must update this template before it can be used.",
      "path": ["changeOrders", "create"],
      "extensions": {
        "code": "REQUIRED_APPROVER_UNRESOLVABLE",
        "statusCode": 400
      }
    }
  ]
}
```

**How to resolve:** someone with permission to manage change order templates must update the template, replacing the required approver or removing their `isRequiredToApprove` flag. Retrying will not help until then.

#### `CANNOT_REMOVE_REQUIRED_REVIEWER`

Returned by `removeReviewersFromStages` when one of the reviewers to remove is a required approver on that stage. Required approvers cannot be removed in any change order status. The request is all-or-nothing: if any reviewer in it is required, no one is removed.

```json
{
  "errors": [
    {
      "message": "User 123e4567-e89b-12d3-a456-426614174004 is a required approver on stage \"Quality Review\" and cannot be removed.",
      "path": ["changeOrders", "removeReviewersFromStages"],
      "extensions": {
        "code": "CANNOT_REMOVE_REQUIRED_REVIEWER",
        "statusCode": 400
      }
    }
  ]
}
```

**How to resolve:** leave required approvers out of the removal request. To check first, read `StageReviewer.isRequiredToApprove` on the stage's reviewers. Whether someone is required is set by the template the change order was created from, not by the change order.

### Change Order Content Value Errors

Custom field values — the `contents` of a change order — are validated against the field's definition in the template whenever they are written, whether through `changeOrders.setContentValue` or through the content values carried by `changeOrders.submitDraft`. See [Field Definitions](https://docs.durohub.com/library-configuration/change-order-workflow-reference.md#field-definitions) for the field types and [Setting Custom Field Values](https://docs.durohub.com/core-concepts/change-orders.md#setting-custom-field-values) for the write call.

All five codes are HTTP `400`, and every one carries two extra keys on `extensions`:

* `field` — the label of the field that was rejected.
* `value` — the rejected value, echoed back. It is capped at 100 Unicode code points and followed by `…` when truncated. For `CONTENT_TOO_MANY_VALUES` it is the supplied values joined with `,` .

| Code                          | Field types                                                                     | Meaning                                                                                                                                                                                                                                                                                                                                                           |
| ----------------------------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CONTENT_TOO_MANY_VALUES`     | `text`, `longtext`, `number`, `currency`, `date`, single-select `list` / `enum` | More than one value was sent for a field that holds at most one.                                                                                                                                                                                                                                                                                                  |
| `CONTENT_VALUE_NOT_AN_OPTION` | `list`, `enum`                                                                  | A value does not exactly match one of the field's configured option **values**. Case and whitespace matter, and display labels are not accepted. Also carries `extensions.options`, the full array of accepted values. A field with no configured options accepts any value. For multi-select fields, only the occurrences newly added in this write are checked. |
| `CONTENT_VALUE_NOT_A_NUMBER`  | `number`, `currency`                                                            | The value is not a finite plain decimal, optionally with an exponent. `12`, `-3`, `1.5`, `.5` and `1e-7` are accepted; empty or whitespace-only values, `1,234`, `+5`, hexadecimal or binary notation, `Infinity` and `NaN` are rejected. Surrounding whitespace is trimmed before the value is stored.                                                           |
| `CONTENT_INVALID_DATE`        | `date`                                                                          | The value is empty or cannot be parsed as a date.                                                                                                                                                                                                                                                                                                                 |
| `CONTENT_DATE_ROLLED_OVER`    | `date`                                                                          | The value parses, but names a calendar date that does not exist, such as `2026-02-30`.                                                                                                                                                                                                                                                                            |

```json
// Sending a display label where the option value is expected
{
  "errors": [
    {
      "message": "\"Change Category\" does not accept \"Lifecycle Promotion\". Allowed options: engineering-change-order, manufacturing-change-order, documentation-change-order.",
      "path": ["changeOrders", "setContentValue"],
      "extensions": {
        "code": "CONTENT_VALUE_NOT_AN_OPTION",
        "statusCode": 400,
        "field": "Change Category",
        "value": "Lifecycle Promotion",
        "options": ["engineering-change-order", "manufacturing-change-order", "documentation-change-order"],
        "service": "foundation"
      }
    }
  ]
}
```

```json
// Two values on a single-value field
{
  "errors": [
    {
      "message": "\"Estimated Cost\" accepts a single value, but 2 were given.",
      "path": ["changeOrders", "setContentValue"],
      "extensions": {
        "code": "CONTENT_TOO_MANY_VALUES",
        "statusCode": 400,
        "field": "Estimated Cost",
        "value": "1200, 1500",
        "service": "foundation"
      }
    }
  ]
}
```

**What is and is not validated:**

* **Only changed values are checked.** A value identical to what is already stored is accepted as-is, so a draft that holds an invalid value from before validation was introduced still saves as long as that field is left alone. Changing such a field to a valid value succeeds.
* **Multi-select reorderings are not a change.** Sending the same occurrences in a different order bypasses validation, but the supplied order is what gets saved. Duplicate occurrences count: `["a", "a"]` is not the same selection as `["a"]`.
* **Clear a field with `values: []`.** An empty array is a clear, not a value, and never fails validation.
* **Dates are normalized.** A valid date is trimmed and stored as an ISO string, so what you read back may differ in form from what you sent.
* **`submitDraft` is atomic.** If any content field in the call is rejected, the whole mutation fails and none of its other changes — content values, documents, type or template — are saved.

{% hint style="warning" %}
Date errors from these operations were previously reported as `BAD_REQUEST`. They now return `CONTENT_INVALID_DATE` and `CONTENT_DATE_ROLLED_OVER`; update any client that branches on the old code.
{% endhint %}

**How to resolve:**

* For `CONTENT_VALUE_NOT_AN_OPTION`, send the option's `value`, not its `label`, and match it exactly. The accepted values are in `extensions.options`; they are also the `value` entries under the field's `options` in the template YAML (see [Options for List/Enum Fields](https://docs.durohub.com/library-configuration/change-order-workflow-reference.md#options-for-listenum-fields)). Do not trim or re-case them on the client.
* For `CONTENT_TOO_MANY_VALUES`, send a one-element `values` array. Only a `list` field with `multiSelect: true` takes more than one value.
* For `CONTENT_VALUE_NOT_A_NUMBER`, strip thousands separators, currency symbols and a leading `+` before sending, and send the number as a plain decimal string such as `"1234.50"`.
* For `CONTENT_INVALID_DATE` and `CONTENT_DATE_ROLLED_OVER`, send a real calendar date in ISO 8601 form, such as `"2026-03-02"`. Check day-of-month against the month before sending.
* None of these errors is transient. Retrying the same request unchanged fails again; correct the value in `extensions.value` for the field in `extensions.field`, then resend.

### Comment Mention Errors

Returned when a comment is created or edited with too many @mentions. The limit applies to the number of distinct people mentioned, not to the number of times they are mentioned: the same person tagged twice counts once, and the check runs on lowercased IDs, so an ID that differs only in case is not a separate mention. The count is taken from the `mentionUserIds` list in the request, not from the comment text. An edit (`comments.update`) is checked the same way as a create (`comments.create`), against the whole list it sends, not only the people it adds. An edit that omits `mentionUserIds`, or sends `null`, keeps the comment's existing mentions and is not checked.

| Code                | Status | Meaning                                                                                                                                                      | How to resolve                                                            |
| ------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------- |
| `TOO_MANY_MENTIONS` | 400    | The comment mentions more than 50 distinct people. Nothing is written: a create does not post the comment and an edit leaves the existing comment unchanged. | Reduce the mentions to 50 or fewer distinct people, or split the comment. |

```json
{
  "errors": [
    {
      "message": "A comment can mention at most 50 people",
      "extensions": {
        "code": "TOO_MANY_MENTIONS"
      }
    }
  ]
}
```

This error carries only `code` on `extensions`. There is no `statusCode` key; the 400 in the table is the code's classification.

`TOO_MANY_MENTIONS` is not transient. Retrying the same request unchanged fails again; remove mentions before resending.

### Export Template Errors

Returned when you manage [export templates](https://docs.durohub.com/exports/export-templates.md) or start a BOM or component-list export with `exportJob.create`.

| Code                              | Status | Meaning                                                                                                                           | How to resolve                                                            |
| --------------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| `EXPORT_TEMPLATE_NOT_FOUND`       | 404    | No template in this library has that `templateId` or `templateName`. Names are case-sensitive, and archived templates don't count | Check the name or ID with `exportTemplate.findAll`                        |
| `EXPORT_TEMPLATE_NAME_TAKEN`      | 409    | Another template in this library already has that name, on `create` or when renaming with `update`                                | Choose a different name, or update the existing template                  |
| `EXPORT_TEMPLATE_LOOKUP_CONFLICT` | 400    | `exportJob.create` was given both `templateId` and `templateName`                                                                 | Send one of them                                                          |
| `EXPORT_NO_DEFAULT_TEMPLATE`      | 400    | No template was named and the library has no default template                                                                     | Name a template, or make one the default with `exportTemplate.setDefault` |
| `EXPORT_CONFIG_REQUIRED`          | 400    | `exportTemplate.create` was given neither `configYAML` nor `configJSON`                                                           | Send one of them                                                          |
| `EXPORT_CONFIG_CONFLICT`          | 400    | Both `configYAML` and `configJSON` were sent                                                                                      | Send one of them                                                          |
| `EXPORT_INVALID_CONFIG`           | 400    | The configuration isn't a valid export template. See below                                                                        | Fix every problem the message lists, then save again                      |

#### `EXPORT_INVALID_CONFIG`

Returned by `exportTemplate.create` and `exportTemplate.update` when the configuration being saved isn't a valid export template, and by `exportJob.create` when `configOverrides` isn't valid. It covers:

* YAML that doesn't parse.
* A missing required key, or a value of the wrong type or outside its allowed set (for example `assembly_depth: deep`).
* A key the template format doesn't have (`bogus_option`, `fields.sort`).
* A column key in `fields.include`, `fields.exclude`, `fields.order` or `mappings` that isn't a system field, `variant`, a `src:` sourcing field, or `attr_` followed by the exact name of an attribute in the library.

HTTP `400`. The message lists every problem, separated by `;`, and `extensions.problems` carries the same list. When Duro can tell what was meant, it adds a suggestion:

```json
{
  "errors": [
    {
      "message": "Invalid export template configuration: unknown key \"bogus_option\"; fields.exclude: unknown column \"mass\" (did you mean \"attr_Mass\"?)",
      "path": ["exportTemplate", "create"],
      "extensions": {
        "code": "EXPORT_INVALID_CONFIG",
        "statusCode": 400,
        "problems": [
          "unknown key \"bogus_option\"",
          "fields.exclude: unknown column \"mass\" (did you mean \"attr_Mass\"?)"
        ]
      }
    }
  ]
}
```

**How to resolve:**

* Fix every problem listed and save again. The full rules and the valid column keys are in [Export Templates](https://docs.durohub.com/exports/export-templates.md#when-duro-refuses-a-template).
* `exportJob.create` checks only the keys in `configOverrides`. An override may repeat any column the template already names, and one that is exactly the settings of an earlier export in the library (a re-export) is accepted as it is. The saved template isn't re-checked when an export runs, so a template saved before these checks keeps exporting until someone saves it again.

### Change Order Export Errors

A change order export package is built asynchronously by an export job. When the job fails, Duro classifies the failure and records it on the job as a `failureReason`. Some reasons are **retryable** (a transient file-service or delivery problem, for example) and some are **permanent** — retrying will fail the same way until the underlying data is fixed.

| `failureReason`                                    | Retryable | Meaning                                                                                                                                                                                                                                                  |
| -------------------------------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DOCUMENT_UNAVAILABLE`                             | No        | A document attached to the change order could not be fetched — typically its file is missing or is tagged with the wrong organization. The job's `blockingDocument` identifies it. See [Documents](https://docs.durohub.com/core-concepts/documents.md). |
| `CHANGE_ORDER_UNAVAILABLE`                         | No        | The change order the job was created for could no longer be read when the package was built.                                                                                                                                                             |
| `JOB_MALFORMED`                                    | No        | The job's stored parameters are invalid and cannot produce a package.                                                                                                                                                                                    |
| `FILE_SERVICE_UNAVAILABLE`, `FILE_SERVICE_TIMEOUT` | Yes       | The file service was unreachable or too slow while downloading documents.                                                                                                                                                                                |
| `PACKAGING_FAILED`, `DELIVERY_FAILED`              | Yes       | The archive could not be assembled or uploaded.                                                                                                                                                                                                          |
| `WORKFLOW_START_FAILED`, `TIMED_OUT`, `UNKNOWN`    | Yes       | The export workflow did not start, exceeded its time budget, or failed for an unclassified reason.                                                                                                                                                       |

Read `retryable` on the export job before offering a retry — it is derived from the reason above, and is `true` for jobs that failed before failure reasons were recorded. Both `retryable` and `blockingDocument` require `library.read` or `exports.create`.

```graphql
# Fields to select on the change order's latest export job
fragment ExportFailureFields on ExportJob {
  id
  status
  failureReason
  retryable
  blockingDocument { documentId name }
}
```

#### `SOURCING_UNAVAILABLE` (BOM and component-list exports)

`ExportFailureReason` also includes `SOURCING_UNAVAILABLE`. It is recorded as the `failureReason` of a BOM or component-list export job that requested sourcing data when the sourcing data could not be retrieved while the sheet was built. Duro never delivers a sheet without the requested sourcing, so the job fails instead. This reason is **retryable**: start the export again once sourcing is available.

{% hint style="info" %}
`SOURCING_UNAVAILABLE` only applies to BOM and component-list exports — it is never returned for change order export jobs. It is an `ExportJob.failureReason` value, not a GraphQL `extensions.code`.
{% endhint %}

#### `EXPORT_CO_PERMANENT_FAILURE`

Returned by `retryChangeOrderExport` when the job being retried failed for a permanent reason. `extensions.failureReason` carries the reason so you can tell the user what to fix.

```json
{
  "errors": [
    {
      "message": "This export failed permanently and cannot be retried until the underlying issue is resolved.",
      "path": ["retryChangeOrderExport"],
      "extensions": {
        "code": "EXPORT_CO_PERMANENT_FAILURE",
        "failureReason": "DOCUMENT_UNAVAILABLE",
        "service": "exports"
      }
    }
  ]
}
```

**How to resolve:**

* Fix the underlying data first — re-upload or correct the document named by `blockingDocument`, or restore the change order.
* Then retry with `force: true`. The guard is skipped and a new export job is started regardless of the previous failure's classification:

  ```graphql
  mutation {
    retryChangeOrderExport(input: { exportJobId: "...", force: true }) {
      id
      status
    }
  }
  ```

{% hint style="warning" %}
`force` does not make the export succeed — it only bypasses the permanent-failure check. Retrying a `DOCUMENT_UNAVAILABLE` job with `force: true` before the document is fixed produces another job that fails with the same reason. Only pass it after you have resolved the cause reported in `failureReason`.
{% endhint %}

### Organization Creation Errors

Creating a new production organization is gated: the account must hold a valid, unused organization-creation grant issued to its verified email address. Self-serve creation without a grant is not yet available. When a create is refused, `extensions.code` identifies why so you can present a clear, distinguishable message. Query [`Me.canCreateOrg`](https://docs.durohub.com/getting-started/current-user.md#checking-whether-a-user-can-create-an-organization) beforehand to know whether to offer the action at all.

The codes below apply to the grant path. Creating a **sandbox** organization under an existing parent goes through a different set of checks — see [Sandbox Organization Errors](#sandbox-organization-errors).

All five are `403`.

| Code                             | Meaning                                                                                                                                                                                                                                                                                                                                                                | How to resolve                                                                                               |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `GRANT_NONE`                     | **The refusal you should expect in practice.** No currently claimable grant was found for the account. A grant that was never issued, has already been consumed, was revoked, has expired, or whose backing package is archived all collapse into this one code — the message is deliberately generic and never reveals whether a grant exists for some other account. | Request a grant from Duro before creating an organization.                                                   |
| `SELF_SERVE_NOT_AVAILABLE`       | The account has no claimable grant **but is on the self-serve allowlist** — it would be eligible to create its own organization, except self-serve creation has not shipped yet. It is the more specific refusal for accounts that would otherwise be permitted, not a broader one.                                                                                    | Request an organization-creation grant from Duro in the meantime.                                            |
| `GRANT_ALREADY_CONSUMED`         | **Race-only.** The grant was pending when it was read, but a concurrent create claimed it first. A grant that was already consumed before the request began returns `GRANT_NONE` instead.                                                                                                                                                                              | Treat as a lost race. Do not retry — the grant is spent. Request a new grant to create another organization. |
| `GRANT_REVOKED`                  | **Race-only.** The grant was revoked in the instant between being read and being claimed. A grant revoked before the request began returns `GRANT_NONE` instead.                                                                                                                                                                                                       | Contact Duro to have a new grant issued.                                                                     |
| `GRANT_BACKING_PACKAGE_ARCHIVED` | **Defensive guard; not reachable on the normal path.** Grants whose backing package is archived are filtered out before the claim, so they surface as `GRANT_NONE`.                                                                                                                                                                                                    | Contact Duro; the grant must be re-issued against an active package.                                         |

```json
{
  "errors": [
    {
      "message": "No valid pending grant was found for this account.",
      "path": ["organization", "create"],
      "extensions": {
        "code": "GRANT_NONE",
        "statusCode": 403,
        "service": "foundation"
      }
    }
  ]
}
```

{% hint style="warning" %}
Do not branch on `GRANT_ALREADY_CONSUMED` or `GRANT_REVOKED` to detect a spent or revoked grant — those two codes are raised **only** when the state changes mid-request, under concurrency. In the ordinary sequential case, a spent, revoked, or expired grant is indistinguishable from no grant at all and returns `GRANT_NONE`. Handle `GRANT_NONE` as the general "you cannot create an organization" case and treat the other two as rare race outcomes.
{% endhint %}

{% hint style="info" %}
[`Me.canCreateOrg`](https://docs.durohub.com/getting-started/current-user.md) is a UI hint that reflects eligibility at query time. Because a grant can be consumed or revoked in the interim, treat the create mutation and these error codes as the source of truth.
{% endhint %}

### Import Job Errors

These codes describe the import **job** as a whole, rather than an individual row. Per-row failures are reported on `rowResults` — see [Row Outcomes](https://docs.durohub.com/core-concepts/importing-components.md#row-outcomes) and [Sourcing Import Errors](#sourcing-import-errors).

| Code                                       | Status | Meaning                                                                                                                                                                                                                                                            | How to resolve                                                                     |
| ------------------------------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- |
| `IMPORT_JOB_TERMINALIZED_DURING_PROMOTION` | 409    | The job was moved to a terminal state — typically because it was [cancelled](https://docs.durohub.com/core-concepts/importing-components.md) — while its components were being committed. The promotion is rolled back, so no component from the sheet is written. | Nothing was partially applied. Re-upload the sheet if the import was still wanted. |

{% hint style="info" %}
Because the promotion is rolled back rather than half-applied, a job that ends this way never leaves components behind. The converse also holds: once a job's components have committed, the job does not report `FAILED` — a later hiccup in the clean-up that follows the commit leaves the job `COMPLETED` with the detail recorded in `errorDetails`.
{% endhint %}

### Sourcing Import Errors

Columns mapped to a [`src:` target](https://docs.durohub.com/core-concepts/importing-components.md#sourcing-columns-src-targets) are applied after the component rows are written. When a sourcing value cannot be applied, the failure is reported on the job's `sourcingResults` — a separate list from `rowResults`, keyed by the same `rowNumber` — with `status: FAILED` and one of these codes in `errors`.

Note that an unrecognized name is generally **not** an error: unknown manufacturers, distributors, and [package types](https://docs.durohub.com/core-concepts/importing-components.md#package-type-resolution) are created on demand. The codes below cover the cases where a name resolves to something the import will not act on, or cannot be resolved at all.

| Code                                           | Target                                 | Meaning                                                                                                                                                                                                                                                                      | How to resolve                                                                                                                   |
| ---------------------------------------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `SOURCING_IMPORT_PACKAGE_TYPE_ARCHIVED`        | `src:packageType`                      | The value matches an **archived** package type. Matching is case-insensitive and covers archived package types, so the name cannot be re-created and the row is failed rather than silently reviving the archived type. Status `409`.                                        | Restore the package type in Duro, or use a different name.                                                                       |
| `SOURCING_IMPORT_PACKAGE_TYPE_AMBIGUOUS`       | `src:packageType`                      | The value matches more than one package type — two existing types differing only by case — so the import cannot choose one. Creating a third would not resolve which one the sheet meant.                                                                                    | Use the exact, unambiguous package name.                                                                                         |
| `SOURCING_IMPORT_PACKAGE_TYPE_UNRESOLVABLE`    | `src:packageType`                      | The package type did not exist and could not be created — typically two rows of the same import racing on the same new name. Status `409`.                                                                                                                                   | Re-upload the sheet. The package type usually exists by then and the retry resolves it.                                          |
| `SOURCING_IMPORT_UNREADABLE_VALUE`             | `src:packageType`                      | The cell is longer than 100 characters, which is a mis-mapped column rather than a package name.                                                                                                                                                                             | Check the column mapping, and shorten the value.                                                                                 |
| `SOURCING_IMPORT_MPN_OWNED_BY_OTHER_COMPONENT` | `src:manufacturer` / `src:mpn`         | The manufacturer and MPN already identify a part that belongs to a different component in this library. A manufacturer part number can belong to only one component. `details` carries the owning component's id. Status `409`.                                              | Fix the MPN on the row, or move the part to this component in Duro.                                                              |
| `SOURCING_IMPORT_VENDOR_ARCHIVED`              | `src:manufacturer` / `src:distributor` | The value names an **archived** vendor. An archived vendor keeps its name, so it is neither reused nor revived by the import. Status `409`.                                                                                                                                  | Restore the vendor in Duro, or use a different name.                                                                             |
| `SOURCING_IMPORT_PART_IDENTITY_CHANGED`        | `src:manufacturer` / `src:mpn`         | The manufacturer part the row matched changed identity, or stopped being available, between being matched and being written — typically because it was edited or removed concurrently. The row is failed rather than written to a part that is no longer the one it matched. | Re-upload the sheet. The row was not partially applied, and on a settled library the retry resolves the part again and succeeds. |

```json
{
  "rowNumber": 7,
  "status": "FAILED",
  "errors": [
    {
      "field": "src:packageType",
      "code": "SOURCING_IMPORT_PACKAGE_TYPE_ARCHIVED",
      "message": "Package type \"SOIC8-W\" is archived"
    }
  ]
}
```

### Sourcing Query Errors

Returned by [`vendorSourcing.componentSourcingByVendor`](https://docs.durohub.com/core-concepts/components.md#components-sourced-by-a-vendor) and the paged vendor list queries [`vendorSourcing.libraryVendors` and `archivedLibraryVendors`](https://docs.durohub.com/core-concepts/sourcing.md#listing-library-vendors-with-paging-and-sorting). Write-side sourcing codes such as `DUPLICATE_PART` are listed on the [Sourcing](https://docs.durohub.com/core-concepts/sourcing.md#error-codes) page; the vendor write codes are below.

| Code                                | Meaning                                                                                                                                                                                                                                                                                                                                                       | How to resolve                                                                                                                                                                                                                                                                                                            |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `COMPONENT_SOURCING_INVALID_CURSOR` | The `after` argument is not a valid pagination cursor. Status `400`.                                                                                                                                                                                                                                                                                          | Restart from the first page by omitting `after`, and only pass back an `endCursor` received from `pageInfo`.                                                                                                                                                                                                              |
| `VENDOR_LIST_INVALID_CURSOR`        | The `pagination.after` argument to `libraryVendors` or `archivedLibraryVendors` is not a valid cursor: it is malformed or empty, came from the other list query, or came from a different `orderBy` field or direction. The message is `Invalid pagination cursor`. Status `400`.                                                                             | Restart from the first page by omitting `after`, and only pass back an `endCursor` received from `pageInfo` of the same query with the same `orderBy`.                                                                                                                                                                    |
| `VENDOR_LIST_OFFSET_WITH_CURSOR`    | The `pagination` argument to `libraryVendors` or `archivedLibraryVendors` has a non-null `offset` — `0` counts — together with a non-null `after`. The two paging styles are exclusive, and the request is refused before the cursor is decoded or anything is queried. The message is `Pass offset or after, not both`. Status `400`.                        | Pass `offset` or `after`, not both: send `offset` alone to jump to a page by number, or `after` alone to continue from a previous page's `endCursor`. See [Listing library vendors with paging and sorting](https://docs.durohub.com/core-concepts/sourcing.md#listing-library-vendors-with-paging-and-sorting).          |
| `VENDOR_LIST_STATUS_FILTERS_BOTH`   | The `filter` argument to `libraryVendors` or `libraryVendorList` has a non-null `approvalStatus` together with a non-null `approvalStatuses` — `[]` counts. The two are alternative forms of the same status filter, and the request is refused before anything is queried. The message is `Pass approvalStatus or approvalStatuses, not both`. Status `400`. | Pass `approvalStatus` or `approvalStatuses`, not both: send `approvalStatuses` alone to match any of several statuses, or `approvalStatus` alone to match one. See [Listing library vendors with paging and sorting](https://docs.durohub.com/core-concepts/sourcing.md#listing-library-vendors-with-paging-and-sorting). |
| `VENDOR_NOT_FOUND`                  | The `vendorId` does not match a vendor in the request's library; another library's vendor gets this error too. A vendor with no matching sourcing rows returns an empty page, not this error; an archived vendor can still return rows. Status `404`.                                                                                                         | Check that the id is the vendor's id in the library named by `x-library`. Vendor ids changed when vendors moved into libraries: see [Vendors moved into libraries](https://docs.durohub.com/core-concepts/sourcing.md#vendors-moved-into-libraries).                                                                      |
| `PERMISSION_NOT_FOUND`              | The caller lacks `components.read` in the library. The query still returns its rows, but each row's `component` is `null` and the response carries this error from the component service's permission check. Status `403`. A caller without `sourcing.vendor.read` gets `FORBIDDEN` for the whole query instead.                                              | Grant the caller's role `components.read` in that library, or don't select `component`.                                                                                                                                                                                                                                   |

### Vendor Write Errors

Returned by the vendor mutations under `vendorSourcing` — `removeFromVendorList`, `saveLibraryVendor`, `createVendor`, `updateVendor`, `updateLibraryVendor` and `addToVendorList` — in the library named by `x-library`. See [Adding, archiving and removing vendors](https://docs.durohub.com/core-concepts/sourcing.md#adding-archiving-and-removing-vendors) and [Saving profile, account and status in one call](https://docs.durohub.com/core-concepts/sourcing.md#saving-profile-account-and-status-in-one-call).

| Code                | Status | Meaning                                                                                                                                                                                                                                           | How to resolve                                                                                                                                                                                                 |
| ------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `VENDOR_IN_USE`     | 409    | `removeFromVendorList` refuses to delete a vendor that any part or quote in the library references. Archived parts and quotes count as references, so a vendor whose sourcing rows were all archived still cannot be removed. Nothing is written. | Archive the vendor with `archiveVendor` instead; it keeps its parts, quotes and history. If it must go, move or delete every part and quote that references it first, including archived ones, then remove it. |
| `VENDOR_NOT_FOUND`  | 404    | The `vendorId` is not a non-archived vendor in the request's library. `saveLibraryVendor` returns it for an archived vendor, an unknown id, or another library's vendor.                                                                          | Check the id against `libraryVendors` in the library named by `x-library`. To edit an archived vendor's list entry, use `changeVendorApprovalStatus` or `updateVendorListEntry`.                               |
| `VENDOR_NAME_TAKEN` | 409    | The library already has a vendor with exactly that name. The check is case-sensitive, so a `checkVendorNameSimilarity` match with reason `EXACT` does not by itself mean a save will be rejected.                                                 | Pick another name, or use the `vendorId` from `checkVendorNameSimilarity` to work with the existing vendor.                                                                                                    |

`VENDOR_IN_USE` is not transient: retrying the removal fails again until the references are gone.

### Identifier Query Errors

Returned by [`identifier.get`](https://docs.durohub.com/core-concepts/components.md#looking-up-identifiers) when it is called in list mode — with `ids` omitted, `null`, or empty — and more than 10,000 identifiers match the filter. The check runs after `filter.type` and `filter.isArchived` are applied, so a narrowed list that still exceeds the cap fails the same way. Exactly 10,000 matches succeed. Nothing is truncated: the query either returns every match or returns this error.

| Code                        | Status | Meaning                                             | How to resolve                                                                                                                                                            |
| --------------------------- | ------ | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `IDENTIFIER_LIST_TOO_LARGE` | 400    | The list would return more than 10,000 identifiers. | Pass a nonempty `ids` list to read specific records — by-ID lookups are exempt from the cap — or narrow with `filter.type` (`CMP`, `PRD`, `DOC`) and `filter.isArchived`. |

The error is not transient. Retrying the same query will fail again; correct the query instead.

```json
{
  "errors": [
    {
      "message": "This library has more than 10000 identifiers. Pass `ids` to look up specific ones, or narrow with `filter.type`.",
      "path": ["identifier", "get"],
      "extensions": {
        "code": "IDENTIFIER_LIST_TOO_LARGE",
        "statusCode": 400
      }
    }
  ]
}
```

The cap is stated only in the message; there is no separate `extensions` field carrying it.

### Integration Access Errors

Writes made on behalf of an integration are checked against the [principal model](https://docs.durohub.com/core-concepts/components.md#integration-access-and-provenance): open attributes are writable by anyone, managed attributes only by principals linked to the component. These codes are returned by component writes (including `reconcile`), by `linkComponent` / `unlinkComponent`, and by `setAttributeAccess`.

| Code                                      | Meaning                                                                                                                                                                                | How to resolve                                                                                                                                                                              |
| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ATTRIBUTE_LOCKED_BY_INTEGRATION`         | The attribute is managed, and the caller is not one of its linked managers. Also covers the **frozen** case — a managed attribute with no linked manager at all is writable by no one. | Link the acting principal to the component and make it a manager of the attribute, or write a different attribute. Read `effectiveAttributeAccess` first to know which fields are editable. |
| `ATTRIBUTE_REQUIRES_COMPONENT_LINK`       | The acting integration manages the attribute but is not linked to this component. Open attributes never raise this — only managed ones.                                                | Call `linkComponent` for that component, then retry.                                                                                                                                        |
| `INTEGRATION_NOT_ENABLED_FOR_LIBRARY`     | The acting integration is not enabled for the library in the `x-library` header (`403`), or an integration that is not enabled was named as an attribute's source of truth (`400`).    | Enable the integration for that library, or target a library where it is enabled.                                                                                                           |
| `INTEGRATION_NOT_FOUND`                   | The referenced integration does not exist. Status `404`.                                                                                                                               | Check the integration id or key.                                                                                                                                                            |
| `ATTRIBUTE_WRITE_DISABLED_FOR_USERS`      | The library's access policy makes the attribute read-only for people, so the web app and user API keys cannot write it. Status `403`.                                                  | Write it through the integration that manages it.                                                                                                                                           |
| `ATTRIBUTE_WRITE_BLOCKED_FOR_INTEGRATION` | The library's access policy explicitly blocks the acting integration from writing the attribute. Status `403`.                                                                         | Write through a principal that is allowed to, or have a library admin change the policy.                                                                                                    |
| `IMPORT_AUTHOR_REQUIRES_CONFIGURE`        | An import was asked to write as an integration, which writes BOM lines under that integration's identity. Status `403`.                                                                | Grant the caller `integrations.configure`, or import without an integration author.                                                                                                         |
| `COMPONENT_NOT_FOUND`                     | The referenced component does not exist in the current library context.                                                                                                                | Check the id and the `x-library` header.                                                                                                                                                    |
| `ATTRIBUTE_NOT_FOUND`                     | The referenced attribute does not exist for the component's category in this library.                                                                                                  | Re-read the category's attributes; ids are library-scoped.                                                                                                                                  |
| `INTEGRATION_CLAIM_NOT_AUTHORIZED`        | The caller may not claim the component for the requested integration.                                                                                                                  | Check the caller's `integrations.configure` permission and that the target integration is the one the request is acting as.                                                                 |
| `CLAIM_REQUIRES_ACTING_INTEGRATION`       | A claim or link was requested on a request that has no acting integration. Duro will not infer one.                                                                                    | Make the call with integration credentials so the request has an acting integration.                                                                                                        |
| `STORE_PRINCIPAL_ALWAYS_READS`            | An access policy tried to give the Duro principal no-read or no-access on an attribute. Duro must always be able to render its own data.                                               | Use receive-only instead, which makes the attribute read-only in the web app while keeping it visible.                                                                                      |

Two further codes guard [exclusive attribute management](https://docs.durohub.com/core-concepts/components.md#attribute-access) — the `EXCLUSIVE_WRITE` write designation, which makes one principal the sole manager of an attribute. Both are returned by `setAttributeAccess`.

| Code                            | Meaning                                                                                                                  | How to resolve                                                                                       |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- |
| `EXCLUSIVE_BLOCKED_BY_MANAGERS` | `EXCLUSIVE_WRITE` was requested for a principal while other principals still hold a write designation on that attribute. | Clear the other principals' write designations first, then retry. Duro will not demote them for you. |
| `EXCLUSIVE_MANAGER_EXISTS`      | A write designation was requested for a principal on an attribute another principal already manages exclusively.         | Remove the existing exclusive designation first, or designate a different attribute.                 |

{% hint style="info" %}
Neither call partially applies: a rejected `setAttributeAccess` leaves every existing designation exactly as it was. Read `accessPolicy` before granting exclusivity to see which principals you need to clear.
{% endhint %}

```json
// Pushing a CAD-managed attribute from an integration that is not linked to the component
{
  "errors": [
    {
      "message": "Attribute \"Mass\" is managed by Onshape, but Onshape is not linked to this component. Link the component to edit its managed attributes.",
      "path": ["component", "update"],
      "extensions": {
        "code": "ATTRIBUTE_REQUIRES_COMPONENT_LINK",
        "statusCode": 403,
        "service": "foundation"
      }
    }
  ]
}
```

### Access Scope Errors

Some writes are governed per component by an **access scope** rather than per attribute. Two scopes are enforced: `BOM` (the lines of an assembly — adding, removing, swapping or re-quantifying them, by any route including `reconcile` and import) and `DOCUMENTS` (a component's document links, and pointing a document at it with `depictsComponentId`). See [Access scopes](https://docs.durohub.com/core-concepts/components.md#access-scopes) and [Who May Change a Component's Documents](https://docs.durohub.com/core-concepts/documents.md#who-may-change-a-components-documents). Read `scopeAccess` on the component first to know whether the write will be accepted.

| Code                                  | Meaning                                                                                                      | How to resolve                                                                           |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
| `SCOPE_LOCKED_BY_INTEGRATION`         | The scope on this component is managed by an integration, and the caller is not that integration.            | Make the change in the managing integration. The message names it.                       |
| `SCOPE_REQUIRES_COMPONENT_LINK`       | The acting integration is designated to manage the scope but is not linked to this component.                | Call `linkComponent` for that component, then retry.                                     |
| `SCOPE_WRITE_DISABLED_FOR_USERS`      | The library's policy makes the scope read-only for people, so the web app and user API keys cannot write it. | Make the change through the integration that manages the scope.                          |
| `SCOPE_WRITE_BLOCKED_FOR_INTEGRATION` | The library's policy explicitly blocks the acting integration from writing the scope.                        | Write through a principal that is allowed to, or have a library admin change the policy. |

All four are `403`, and the message names the scope. A library with no policy configured for a scope never returns them: the scope is open to every caller.

### Entitlement Errors

Some features and limits are governed by your organization's **subscription plan**. When a request targets a feature your plan does not include, or would exceed a quota your plan allows, the API returns an entitlement error. Match on `extensions.code` — it is the stable, programmatic key.

| Code                        | Meaning                                                                                                                                                                                                                                                                                                                                                  | How to resolve                                                                     |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `FEATURE_NOT_IN_PLAN`       | The operation requires a feature that your organization's plan does not include. For example, configuring [Enterprise SSO](https://docs.durohub.com/account-management/enterprise-sso.md) requires the `SSO_SAML` entitlement and [SCIM provisioning](https://docs.durohub.com/account-management/scim-provisioning.md) requires the `SCIM` entitlement. | Contact your Duro account team to add the feature to your plan.                    |
| `SEAT_LIMIT_REACHED`        | The operation would exceed the number of user seats your plan allows.                                                                                                                                                                                                                                                                                    | Remove unused members, or contact your Duro account team to raise your seat count. |
| `ENTITLEMENT_LIMIT_REACHED` | The operation would exceed another quota your plan allows (sandbox organizations, for example). The message names the specific limit, and `extensions.entitlement` carries its machine key.                                                                                                                                                              | Reduce usage below the limit, or contact your Duro account team to raise it.       |

All three are `403`. The messages interpolate the specific feature or counts, so branch on `code` — and, for `ENTITLEMENT_LIMIT_REACHED`, on `extensions.entitlement`.

```json
// Configuring SAML on an organization whose plan lacks the SSO_SAML entitlement
{
  "errors": [
    {
      "message": "SSO / SAML is not included in your plan.",
      "path": ["organization", "configureSaml"],
      "extensions": {
        "code": "FEATURE_NOT_IN_PLAN",
        "statusCode": 403,
        "service": "foundation"
      }
    }
  ]
}
```

```json
// Exceeding a quota — here, the sandbox_orgs limit on the parent organization
{
  "errors": [
    {
      "message": "Sandbox organizations limit reached (3/3). Upgrade your plan to increase this limit.",
      "path": ["organization", "create"],
      "extensions": {
        "code": "ENTITLEMENT_LIMIT_REACHED",
        "entitlement": "sandbox_orgs",
        "statusCode": 403,
        "service": "foundation"
      }
    }
  ]
}
```

{% hint style="info" %}
Entitlement enforcement applies to organizations with a subscription. These errors surface the limit that was hit so you can act on it — key on `extensions.code` rather than the human-readable `message`, which may change.
{% endhint %}

### Sandbox Organization Errors

[Sandbox organizations](https://docs.durohub.com/account-management/sandbox-organizations.md) are metered against the parent organization's `sandbox_orgs` entitlement. Pass `parentOrganizationId` to `organization.create` to request one. These codes can come back when a sandbox operation is refused.

| Code                        | Status | Operation                                 | Meaning                                                                                                                                                                                                                                                                                                            |
| --------------------------- | ------ | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `SANDBOX_PARENT_FORBIDDEN`  | 403    | Create with `parentOrganizationId`        | The chosen parent cannot host the sandbox. The parent must exist, be an active production (non-sandbox) organization that you are the **Site Admin** of, and have a subscription. Sandboxes cannot be nested, so a sandbox can never be a parent. Being an Org Admin rather than the Site Admin is not sufficient. |
| `SANDBOX_NAME_TAKEN`        | 409    | Create with `parentOrganizationId`        | A sandbox reuses its parent's company, so its name must be unique alongside the parent and every sibling sandbox. Unlike the other three, this one is user-fixable: prompt for a different name.                                                                                                                   |
| `SANDBOX_NOT_AVAILABLE`     | 409    | Create with `parentOrganizationId`        | Sandbox creation is not currently enabled. Refresh your creation options and retry — the request is refused rather than silently falling through to the grant path, so no grant is consumed.                                                                                                                       |
| `SANDBOX_ARCHIVE_FORBIDDEN` | 403    | `organization.archiveSandboxOrganization` | The target cannot be archived through this mutation. It only archives sandbox organizations you administer — production organizations, and sandboxes you do not administer, are rejected.                                                                                                                          |

{% hint style="warning" %}
Exceeding the parent's sandbox quota does **not** return `SANDBOX_PARENT_FORBIDDEN`. It returns [`ENTITLEMENT_LIMIT_REACHED`](#entitlement-errors) with `extensions.entitlement` set to `sandbox_orgs`. `SANDBOX_PARENT_FORBIDDEN` covers only eligibility of the parent and your role on it.
{% endhint %}

`SANDBOX_PARENT_FORBIDDEN` and `SANDBOX_ARCHIVE_FORBIDDEN` are deliberately generic: several distinct causes collapse into one message so the response never reveals whether a given organization exists or why exactly it was refused. Do not try to infer the specific cause from them.

```json
// Creating a sandbox under an ineligible parent
{
  "errors": [
    {
      "message": "You cannot create a sandbox organization under that parent.",
      "path": ["organization", "create"],
      "extensions": {
        "code": "SANDBOX_PARENT_FORBIDDEN",
        "statusCode": 403,
        "service": "foundation"
      }
    }
  ]
}
```

```json
// Archiving an organization that is not an archivable sandbox
{
  "errors": [
    {
      "message": "You cannot archive that sandbox organization.",
      "path": ["organization", "archiveSandboxOrganization"],
      "extensions": {
        "code": "SANDBOX_ARCHIVE_FORBIDDEN",
        "statusCode": 403,
        "service": "foundation"
      }
    }
  ]
}
```

{% hint style="info" %}
Before offering a "create sandbox" action, query `orgCreationOptions` to check whether the user can create a sandbox and which parent organizations still have headroom. See [Sandbox Organizations](https://docs.durohub.com/account-management/sandbox-organizations.md).
{% endhint %}

### Best Practices

* Implement proper error handling
* Add retry logic for rate limits that honours `Retry-After` (see [Handling 429s](https://docs.durohub.com/rate-limits/handling-429s.md))
* Log errors for debugging
* Handle network timeouts
* Provide user-friendly error messages

### Error Recovery

```typescript
async function queryWithRetry(query: string, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await executeQuery(query);
    } catch (error) {
      if (!isRetryableError(error) || attempt === maxRetries) {
        throw error;
      }
      // On RATE_LIMITED, the server says how long to wait (seconds).
      const retryAfter = error.extensions?.code === 'RATE_LIMITED'
        ? error.extensions.retryAfter
        : undefined;
      await delay(retryAfter ? retryAfter * 1000 : exponentialBackoff(attempt));
    }
  }
}
```

See [Handling 429s](https://docs.durohub.com/rate-limits/handling-429s.md) for a complete retry helper.

### Next Steps

Join our [Developer Community](https://docs.durohub.com/community/developer-community.md) for support and discussions.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.durohub.com/advanced-topics/error-handling.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
