ConnectCloud Developers

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, 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) 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.

View as Markdown