Bad Request

Status code 400 Bad Request

Description The input message is incorrect. Look for more details in the issues property.

The following issue types may be returned by any API:

Issue type description

urn:problem-type:belgif:input-validation:schemaViolation

violation of the OpenAPI description of the API

urn:problem-type:belgif:input-validation:invalidInput

Request contains invalid input

This issue type is used when the input is invalid against validations that aren’t formally expressed in the OpenAPI description.

urn:problem-type:belgif:input-validation:unknownInput

Request contains an unknown input field (see [req-valid])

urn:problem-type:belgif:input-validation:referencedResourceNotFound

A resource referenced in the request by its identifier can’t be found.

This issue type is only used for resource identifiers in header or query parameters or in the request body. For resource identifiers in the request path, a Resource Not Found Problem is returned instead, with a 404 status code.

APIs can provide their own types for other input validation issues that require specific handling by client applications. Additional issue types SHOULD be defined as URNs in one of following formats:

  • urn:problem-type:<org>:input-validation:<type>

  • urn:problem-type:<org>:input-validation:<api>:<type>

Issues follow the same structure as a Problem, but don’t use the status or instance properties. As for problems, API clients can use the type to determine how the handle an issue. They should not parse the title or detail properties to extract information; additional properties are a more suitable and less error-prone way to obtain such information.

POST /enterprises/abc

{
  "name": "exampleEnterprise",
  "boardMembers": [
    {
      "ssin": "12345678901",
      "period": {
         "startDate": "2020-12-31",
         "endDate": "2020-01-01"
      }
    },
    {
      "ssin": "98765432109",
      "period": {
         "startDate": "2023-01-01",
         "endDate": "2024-01-01"
      }
    }
  ]
}

returns

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

{
  "type": "urn:problem-type:belgif:badRequest",
  "href": "https://www.belgif.be/specification/rest/api-guide/problems/badRequest.html",
  "title": "Bad Request",
  "status": 400,
  "detail": "The input message is incorrect",
  "instance": "urn:uuid:123456-1234-1235-4567489798",
  "issues": [
    {
      "type": "urn:problem-type:belgif:input-validation:schemaViolation",
      "href": "https://www.belgif.be/specification/rest/api-guide/issues/schemaViolation.html",
      "title": "Input isn't valid with respect to schema",
      "detail": "enterpriseNumber abc should be numeric",
      "in": "path",
      "name": "enterpriseNumber",
      "value": "abc"
    },
    {
      "type": "urn:problem-type:cbss:input-validation:replacedSsin",
      "href": "https://api.example.org/demo/v1/problems/replacedSsin",
      "title": "SSIN has been replaced. Use new SSIN.",
      "detail": "SSIN 12345678901 has been replaced by 23456789012",
      "in": "body",
      "name": "/boardMembers/0/ssin",
      "value": "12345678901",
      "replacedBy": "23456789012"
    },
    {
      "type": "urn:problem-type:belgif:input-validation:referencedResourceNotFound",
      "href": "https://www.belgif.be/specification/rest/api-guide/issues/referencedResourceNotFound.html",
      "title": "Referenced resource not found",
      "detail": "Person referenced as board member with SSIN '98765432109' does not exist",
      "in": "body",
      "name": "/boardMembers/1/ssin",
      "value": "98765432109"
    },
    {
      "type": "urn:problem-type:belgif:input-validation:invalidInput",
      "href": "https://www.belgif.be/specification/rest/api-guide/issues/invalidInput.html",
      "title": "Invalid input",
      "detail": "endDate of a period should be after its startDate",
      "in": "body",
      "name": "/boardMembers/0/period",
      "value": {
        "startDate": "2020-12-31",
        "endDate": "2020-01-01"
      }
    }
  ]
}
InputValidationProblem schema definition (from problem-v1.yaml)
InputValidationProblem:
  type: object
  allOf:
  - $ref: "#/components/schemas/Problem"
  properties:
    issues:
      type: array
      items:
        $ref: "#/components/schemas/InputValidationIssue"
InputValidationIssue:
  type: object
  description: |
    An issue detected during input validation.

    `status` is usually not present.
    `href`, if present, refers to documentation of the issue type.
    Additional properties specific to the issue type may be present.
  allOf:
    - $ref: "#/components/schemas/Problem"
  properties:
    in:
      type: string
      description: The location of the invalid input
      enum:
        - body
        - header
        - path
        - query
    name:
      type: string
      description: The name of the invalid input
    value:
      description: The value of the erroneous input
      # no type specified, allowing any type. This is valid in OpenAPI even though some editors may indicate an error

The possible type values used within issues should be documented for each API. They follow the same URN structure as problem types. It is RECOMMENDED to use input-validation as infix to distinguish them.

InputValidationProblem replaces InvalidParamProblem previously used in this guide, which is now deprecated.