Errors and responses

The response envelope

JSON endpoints return one envelope shape:

{
  "Data": { },
  "Errors": [],
  "Warnings": [],
  "Success": true
}

Check Success first. On failure, Data is usually null and Errors explains why; Warnings uses the same error shape for non-blocking notices (for example, schema-change plans that need confirmation). The exceptions to the envelope are file downloads (raw content), low-level protocol failures such as malformed JSON or an unknown route, and unhandled server failures. Protocol and unhandled failures return an HTTP problem response.

An unhandled server failure returns HTTP 500 with a safe Problem Details body. It does not expose the exception message, stack trace, SQL, paths, or other internal details:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.6.1",
  "title": "An error occurred while processing your request.",
  "status": 500,
  "correlationId": "e4318a5f51994841ad733f40b5f216d8"
}

The same value is returned in the X-Correlation-ID response header. Record it when reporting an unexpected failure; operators can use it to find the corresponding server-side diagnostics without exposing those diagnostics to the caller. A caller may also send X-Correlation-ID on the request to carry an existing trace identity through the operation.

The error shape

Each entry in Errors and Warnings has:

Property	Meaning
`Code`	Stable machine-readable code — branch on this, never on the message.
`Message`	Human-readable text, localized to the workspace locale.
`Field`	The request property the error refers to, when field-specific.
`Target`	Optional identifier of the object the error refers to.
`Metadata`	Optional string map with error-specific context values.
`Type`	`0` Business (state/rules), `1` Validation (bad input), `2` System.
`Severity`	`0` Info, `1` Warning, `2` Error.

Codes

Codes are stable dotted strings shaped as domain.subject.reason, for example moltaro.definitions.name.required or moltaro.fields.key.exists. They double as localization keys, so the same failure always carries the same code in every locale. A curated catalog for core entity configuration and runtime record writes is in the error code reference. Other published modules return the same error shape and stable codes without being enumerated there.

Common patterns:

*.required — a mandatory request value is missing;
*.invalid — a value is present but not acceptable;
*.exists / *.duplicate — a uniqueness rule was hit;
*.notFound — the addressed object does not exist or is not visible;
*.conflict — the RowVersion you sent no longer matches the stored record; re-read the object and retry with the fresh version.

Field paths

Field names the request property using its PascalCase JSON name, e.g. AuditTrailRetentionDays. For items inside collections the path includes the index and nested property: DisplayFields[3].Key, PresentationRules[0].Template.

HTTP status codes

Failures still use meaningful HTTP statuses — 400 validation, 403 forbidden, 404 not found, 409 concurrency/state conflict — with the envelope in the body. Treat the envelope’s Errors as the source of detail and the status code as a coarse category.

Unhandled 500 responses use Problem Details instead of the envelope. Treat them as unknown outcomes: preserve correlationId, verify whether the intended mutation committed, and follow the operation’s documented recovery or idempotency procedure before retrying.

Do not retry every non-success response. Correct a 400, ask the user or administrator to resolve a missing credential or permission on 401/403, verify the workspace API origin and re-discover ids on 404, and re-read and merge current state on 409. A coding agent must not create credentials or grant itself permissions through administrative APIs.

The complete response strategy, including safe retries after unknown outcomes, idempotency keys, build/job polling, concurrency values, and a recovery table, is in Reliable API automation.