Error Messages

The OpenPLZ API returns error messages as JSON objects formatted according to RFC 9457.

What is RFC 9457?

RFC 9457 is a standard by the Internet Engineering Task Force (IETF) that defines a structured format for representing errors in HTTP APIs.

Problem Details

At the core of RFC 9457 is the Problem Details object, a JSON document included in the response body of an API query when errors occur. The OpenPLZ API implements it with the following fields:

type (string)

A URI reference that identifies the type of error. This is typically a reference to the specification of the HTTP status code on the web.

Example: "https://tools.ietf.org/html/rfc9110#section-15.5.1"

title (string)

A short, human-readable summary of the problem.

Example: "One or more validation errors occurred."

status (integer)

The HTTP status code describing the error. It should match the status code in the HTTP response header.

Example: 400

errors (object)

(Optional) A JSON object containing additional details about the error.

Example:

{
    "pageSize": [
      "The field pageSize must be between 1 and 50."
    ]
}

traceId (string)

A unique identifier that can be used for tracing in distributed systems.

Example: "00-abc123def456789ghi-xyz987uvw654321tqr-01"

Example

The API call

https://openplzapi.org/de/Streets?name=Pariser%20Platz&locality=Berlin&page=1&pageSize=99

results in the following error message:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "pageSize": [
      "The field pageSize must be between 1 and 50."
    ]
  },
  "traceId": "00-0274bb16dcdf462bf27a7faedeacc79f-05c5cd5b5d411f8e-00"
}

Analysis of the error:

• The server cannot process the request because it is not properly formulated (HTTP error code 400: Bad Request).

• It is evident that there is an issue with the validation of the query parameters ("One or more validation errors occurred.").

• And indeed, the pageSize parameter has a value (99) outside the valid range (only 1–50).