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:
{
"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 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: 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 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,5xxand network errors, with exponential backoff and jitter (for example 1 s, 2 s, 4 s, … capped at 60 s, at most 5 attempts). GET,PUTandDELETEare safe to retry. ForPOSTrequests that create something, send anIdempotency-Keywhere the endpoint supports it (see Idempotency and concurrency) so a retry cannot create a duplicate.- Never retry
4xxanswers other than429unchanged: 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.