# Errors

Every API answers an error with the same JSON object: a human-readable `error` and a stable `code`, plus the
field the error refers to where there is one:

```json
{
  "error": "Ein Pflichtfeld fehlt.",
  "code": "missing_fields",
  "field": "title",
  "missingFields": ["title", "customFields.betroffenes_system"]
}
```

| Field | Meaning |
|---|---|
| `error` | a human-readable message (English or German, may change: never parse it) |
| `code` | a stable machine-readable code in `snake_case`: **branch on this** |
| `field` | the request field the error refers to, as a JSON path (`title`, `lines[2].quantity`), if any |
| `missingFields` | required fields that are missing (`422 missing_fields`) |
| `details` | further facts where a code has them: `fields` (every invalid field of a request, each with `field`, `rule` and `message`), `counts` (what still uses a row that cannot be deleted), `redirect` (where a moved resource went) |

The codes a module can return are listed in its `Error` schema in the reference. Codes never change their
meaning; new codes may be added, so treat an unknown code like its HTTP status. Every module answers in this shape,
so every error carries a `code`.

## Codes every module uses

| Code | Status | Meaning |
|---|---|---|
| `invalid` | `400` | malformed request or an invalid value; `field` names it, `details.fields` lists every invalid field. Also for a bad `limit`, `offset` or `cursor` of a list |
| `unauthorized` | `401` | token missing, expired or invalid |
| `forbidden` | `403` | the token lacks a permission |
| `tenant_required` | `403` | the token has no active tenant |
| `session_required` | `403` | the route needs a person's sign-in session, not an API key |
| `person_required` | `403` | the route is not available for service accounts |
| `not_found` | `404` | the resource does not exist **or is not visible to you** |
| `version_conflict` | `409` | the `version` you sent is not the current one: re-read and apply your change again |
| `duplicate` | `409` | the resource exists already |
| `in_use` | `409` | still referenced elsewhere (`details.counts` may say by what) |
| `invalid_state` | `409` | the current state of the resource does not allow the action |
| `missing_fields` | `422` | required fields are missing (`missingFields`) |
| `too_large` | `413` | the request body is too large |
| `rate_limited` | `429` | [rate limit](/guides/rate-limits) exceeded |
| `internal` | `500` | unexpected error; the message is always the same, details stay in our logs |
| `unavailable` | `503` | the service or one of its dependencies is temporarily unavailable |

**`400` or `422`?** `400 invalid` means the request itself is wrong – a value has the wrong type or format,
is out of range or names something that does not exist. `422` means the request is well-formed but a business rule
refuses it: a workflow does not allow the transition, required fields of the target state are missing, the other
module refused a handoff. A `422` always carries its own code.

## Status codes

| Status | Meaning | Retry? |
|---|---|---|
| `400` | malformed request, invalid value (`invalid`) | no, fix the request |
| `401` | token missing, expired or invalid (`unauthorized`); key exchange refused (`invalid_api_key`); the person's session behind a forge planning agent run has expired (`session_expired`) | exchange the key again once, then stop |
| `403` | the token lacks a permission (`forbidden`), has no tenant (`tenant_required`) or the route needs a portal session (`session_required`); the action needs a person, not a service account (`person_required`); a confidential forge item would be hidden from you in the target project (`confidential_target`) | no |
| `404` | the resource does not exist **or is not visible to you** (other tenant, confidential, members-only space); a forge item moved to another project: `moved` with `details.redirect` | no (follow `details.redirect`) |
| `409` | conflict: stale `version` (`version_conflict`), duplicate (`duplicate`), still in use (`in_use`), state does not allow it (`invalid_state`, `locked`; forge iterations: `iteration_active`, `iteration_closed`, `iteration_not_planned`, `iteration_not_active`); [handoff and conversion](/guides/handoffs): `converted` (read-only tombstone), `conversion_pending`, `forwarded` (customer reply to a forwarding stub), `handoff_state`, `handoff_pending`, `has_children`; a forge planning agent run is still active in the conversation (`run_active`); the label of a forge module keeps its name (`module_label`); a master data customer or supplier number is taken by another address (`customer_number_taken`, `supplier_number_taken`, with `field`) | after re-reading the resource |
| `413` | body too large (`too_large`) | no |
| `422` | a business rule refuses the request: workflow refuses a transition (`transition_denied`), required fields missing (`missing_fields`), comms rejections (`unknown_template`, `invalid_recipient`, …), the other module refused a handoff (`handoff_refused`) | no |
| `423` | a running workflow locks the document (Trade: `workflow_locked`) | after the workflow step is done |
| `429` | [rate limit](/guides/rate-limits) exceeded (`rate_limited`; also too many active forge planning agent runs or open live streams) | yes, after `Retry-After` seconds |
| `500` | unexpected error (`internal`) | yes, with backoff |
| `502`, `503`, `504` | service temporarily unavailable (`unavailable`; the other module of a handoff is not configured: `forge_unavailable`, `desk_unavailable`) | yes, with backoff |

## Retrying safely

- Retry only `429`, `5xx` and network errors, with exponential backoff and jitter (for example
  1 s, 2 s, 4 s, … capped at 60 s, at most 5 attempts).
- `GET`, `PUT` and `DELETE` are safe to retry. For `POST` requests that create something, send an
  `Idempotency-Key` where the endpoint supports it (see
  [Idempotency and concurrency](/guides/idempotency-and-concurrency)) so a retry cannot create a
  duplicate.
- Never retry `4xx` answers other than `429` unchanged: they will fail again.

## 404 instead of 403

To avoid revealing what exists, the APIs answer `404` for resources you may not see, for example
an item in a members-only space or a confidential item you are not involved in. If you are sure
an item exists, check the permissions of your key or service account.
