What does a RESTCONF ietf-restconf:errors response body contain, and how does the server choose its encoding?

## Where the errors body comes from RESTCONF reports success or failure through **HTTP status codes**, but a status code alone cannot say which leaf was wrong or why. RFC 8040 Section 7 therefore carries over the detail that a NETCONF server puts in its `<rpc-error>` element (RFC 6241 §4.3) and returns it as YANG data: the **`yang-errors`** template in the `ietf-restconf` module. Its shape is a container holding a list, because one request can fail for several reasons at once: ```json { "ietf-restconf:errors": { "error": [ { "error-type": "protocol", "error-tag": "invalid-value", "error-path": "/example-ops:input/delay", "error-message": "Invalid input parameter" } ] } } ``` This is RFC 8040's own example of a `400 Bad Request` for an operation input that failed validation. ## The fields | Field | Required | What it tells you | |---|---|---| | `error-type` | **yes** | the layer that failed: `transport`, `rpc`, `protocol` or `application` | | `error-tag` | **yes** | the NETCONF error tag, such as `invalid-value`, `malformed-message`, `unknown-element`, `access-denied`, `in-use` | | `error-app-tag` | no | a more specific tag defined by a data model or implementation | | `error-path` | no | an **instance-identifier** naming the node the error is about | | `error-message` | no | a human-readable description | | `error-info` | no | anydata with additional detail | Automation should branch on `error-tag` and `error-app-tag`; `error-message` is text for people and has no defined vocabulary. ## When a body is sent RFC 8040 Sections 5.4 and 7.1 set the rules by status class: - **4xx**: the server SHOULD send the errors body, **except** for `403 Forbidden`, which is exempt from that SHOULD; a client must cope with a bare 403. - **5xx**: the server MAY send it. - **1xx, 2xx, 3xx**: error information MUST NOT be returned, because these are not errors. Section 7 also maps NETCONF error tags to status codes, for example `invalid-value` to 400, 404 or 406; `malformed-message`, `unknown-element` and `unknown-namespace` to 400; `access-denied` to 401 or 403; and `in-use`, `lock-denied` and `data-exists` to 409. Which tag a server picks for a particular encoding mistake, such as an unqualified member name or a `uint64` sent as a number, is not dictated by the RFC, so do not hard-code one. ## Choosing the encoding The `Content-Type` of the errors body MUST be `application/yang-data`, optionally with a structured syntax suffix. The choice follows a fixed order: 1. If the request had an `Accept` header, the client SHOULD have listed the encodings it wants, and the server uses one. 2. With no `Accept`, the server SHOULD reuse the suffix of the request body (`+json` in, `+json` out), or MAY choose any format it supports. 3. With no request body either, the server MUST pick `application/yang-data+xml` or `application/yang-data+json` by its own preference. So a client that sent JSON without `Accept` should normally get JSON back, but a `DELETE` with no body and no `Accept` may return its error in XML. RFC 8040's lock-denied example sends `Accept: application/yang-data+json` on a `DELETE` for exactly this reason. ## Reading error-path in each encoding `error-path` is typed `instance-identifier`, so its spelling follows the encoding of the body it is in: - **JSON**: RFC 7951 rules, module names on the first node and wherever the module changes, list entries as predicates, for example `/example-jukebox:jukebox/library/artist[name='Example Artist']`, the form RFC 8072's JSON example uses. - **XML**: prefixes bound by `xmlns` declarations on the `error-path` element, as in RFC 8040's `/rc:restconf/rc:data/jbox:jukebox`. Neither is the request URI syntax, which writes keys after `=`. A tool that tries to turn `error-path` into a URL by string replacement will misfire on predicates and module changes. ## The same structure inside YANG Patch RFC 8072's YANG Patch reuses the `errors` grouping rather than inventing its own. Its `ietf-yang-patch:yang-patch-status` reply carries either **global errors**, for problems unrelated to one edit, or an `edit-status` list with an `errors` container per failed edit, identified by its `edit-id`. The fields, the mandatory pair and the `error-path` encoding are exactly the ones above, so code that reads a plain RESTCONF error body can read each edit's errors with no new logic; RFC 8072 shows such an entry with `error-tag` `data-exists` for a song that already existed. ## A diagnostic routine 1. Read the status code: 415 means the body's media type was refused before any data was examined, a 406 most often means no acceptable reply format, and a 400 usually means the body decoded but broke a rule. 2. Read `error-tag`, then `error-app-tag` if present. 3. Read `error-path` with the instance-identifier rules to find the node. 4. Use `error-message` for the human explanation and log the whole list, since several entries may be present.