ADR 4: HTTP error code guidelines

Status

accepted

Context

The REST API needs a common way of using status codes for errors.

Decision

500 for anything that is related to a system failure either directly on the server that is processing the request or on a dependency

404 whenever an entity is not found by its own identifier

409 if the status of the entity (or one of its dependencies) is not in the required state, or if there is an action already ongoing that would prevent a successful execution, or if the entity that is being created already exists

422 when 400 doesn’t apply because the request is syntactically correct but semantically it doesn’t make sense based on the business rules.

400 whenever the request is not processable because it is missing data, or in the wrong format, anything that prevents the server from understanding the request.

Consequences

We have a guideline of error codes. See also JX-R response status codes section