What this is about
When something goes wrong in CRMS, you never get a sentence back, but a key. A key is a fixed name in kebab-case, meaning lower case with hyphens, for example template-not-found. The frontend translates it into the language of the person in front of the screen.
The shape
POST /crms/templates
{ "key": "audit-report", "outputType": "DOCUMENT" }422
{
"messageKey": "validation-failed", ← the key
"code": "422", ← the status code, as text
"layer": "crms", ← where it was refused
"violations": [ ← only for field errors
{ "field": "scope", "rule": "required" },
{ "field": "defaultLocale", "rule": "required" }
]
}| Field | Meaning |
|---|---|
messageKey | the key, parameters follow after | |
code | the HTTP status code as text, for example "404" |
layer | always crms for CRMS |
violations | every violated field with field and rule. Missing when there are none |
The shape is called ErrorAnswer and is shared by all modules. CDMS and CIAS answer the same way, see The error format.
Keys with parameters
Some keys carry parameters: additional values your frontend can insert into the translated text. They follow the key, separated by |.
messageKey | Meaning |
|---|---|
request-too-large|16777216 | the body is larger than 16777216 bytes |
format-not-offered|DOCX | this installation does not offer DOCX |
template-scope-not-admitted|user | the scope USER is not admitted here |
A parameter names a field, a limit or a format, never a value from your request.
Field errors: violations
Two keys come with a list of violations.
- the HTTP interface checks the shape and fields of the request
- rules
required,invalid,not-allowed - fields in lists are named e.g.
content.assets[0].content - path variables are named as in the path:
edition,variant,revision
- the payload does not match the template's field rules
- fields like
customer.name - rules like
requiredorpayload-too-large - the same rules as
/crms/render/validate
| Rule | Meaning |
|---|---|
required | the field is missing or null. reference is required with FINAL |
invalid | the value does not fit, has the wrong JSON type, is not a UUID in long form, or a reason for documents is not a key |
not-allowed | an unknown field, or pdfProfile with a format other than PDF |
The payload rules are described in The payload check.
How the status code is chosen
The CRMS modules know nothing about HTTP. They only throw a key. The CRMS HTTP interface has one table that gives every key a status code.
| Error from CRMS? | Key in the table? | Response |
|---|---|---|
| yes | yes | the key with its status from the table |
| yes | no | the key with 500 |
| no | – | 500 internal-error, without text |
Errors that Spring reports itself, such as a wrong HTTP method or a Content-Type other than JSON when rendering, are answered by Spring with its own status.
Status codes and their keys
| Status | Meaning | Keys |
|---|---|---|
| 400 | body is not JSON | malformed-json |
| 401 | nobody signed in | crms-authentication-required |
| 403 | role missing | template-write-denied, approval-role-missing, approval-author-excluded, document-access-denied |
| 404 | not there or not visible | template-not-found, document-not-found, document-key-unknown |
| 409 | state does not fit | template-edition-exists, template-variant-exists, template-draft-changed, template-draft-missing, template-review-pending, template-revision-not-in-review, approval-already-given, template-rollback-target-invalid, template-not-published, template-concurrent-change, document-revisions-disabled, transient-documents-disabled, journal-concurrent-change, document-retention-active, document-legal-hold-active, document-legal-hold-inactive, document-concurrent-change, document-locked |
| 410 | erased | document-erased, document-key-destroyed |
| 413 | body too large (templates, document reasons) | request-too-large |
| 415 | encoding not supported | content-encoding-unsupported |
| 422 | content refused | validation-failed, payload-rejected, all template-… rules for scope, reason, source, fields and assets, template-syntax-error, template-render-failed, render-output-too-large, render-asset-unknown, format-not-offered, format-not-for-template, transient-requires-system-template, template-svg-rejected, template-svg-not-for-output-type, attachments-not-for-final, attachments-not-for-format, render-resource-refused, render-pdf-failed, render-word-invalid, render-word-failed, render-table-invalid, render-csv-single-sheet, render-mode-not-for-format |
| 500 | error in operation | internal-error, render-failed, timestamp-failed, timestamp-certificate-expired, document-key-unavailable, document-decryption-failed, document-integrity-failed, document-object-missing, document-seal-failed, storage-versioning-missing |
| 502 | file storage does not answer properly | storage-failed |
| 503 | no capacity right now | render-capacity-exhausted, render-interrupted |
| 504 | rendering took too long | render-timeout |
A render body that is too large is not a 413, but 422 payload-rejected with the rule payload-too-large. The limits when rendering are described in Limits when rendering.
The keys of the client
The keys of crms-client (crms-authentication-required, crms-access-denied, crms-unavailable) arise in the calling application, not in the CRMS service. They are described in The client for a separate service.