README.md

problems

Problem registry for SmartBear API responses conforming to Problem Details RFC 9457 (formally RFC 7808).

If your goal is to improve error handling in your next API, check out our public reusable Problem Details domain which you can reference ($ref) from with your OpenAPI descriptions. 🚀

Contribute

If you would like to add a new problem entry to the registry, submit a PR with the following type of changes:

• Create a new markdown file in the ./src/pages directory with the problem name as the filename (e.g. missing-body-property.md). Distinct words should be hyphen separated in the filename.
• The structure of the markdown should follow other problems already defined within ./src/pages directory.
• When supplying examples that specify an errors array object, it must conform to the JSON Schema specified below.
• Add a new card component to the ./src/pages/index.astro file. An example of a card component is as follows:

    <Card
        href="./missing-body-property"
        title="Missing Body Property"
        body="The request is missing an expected body property 🔍"
    />

Errors JSON Schema

When necessary, a Problem Detail response MAY include additional detail on the problems that have occurred. The additional errors MUST be under the errors collection which itself follows the following schema:

{
    "$schema": "https://json-schema.org/draft/2019-09/schema",
    "type": "object",
    "properties": {
      "type": {
        "type": "string",
        "description": "A URI reference that identifies the problem type.",
        "format": "uri",
        "maxLength": 1024
      },
      "status": {
        "type": "integer",
        "description": "The HTTP status code generated by the origin server for this occurrence of the problem.",
        "format": "int32",
        "minimum": 100,
        "maximum": 599
      },
      "title": {
        "type": "string",
        "description": "A short, human-readable summary of the problem type. It should not change from occurrence to occurrence of the problem, except for purposes of localization.",
        "maxLength": 1024
      },
      "detail": {
        "type": "string",
        "description": "A human-readable explanation specific to this occurrence of the problem.",
        "maxLength": 4096
      },
      "instance": {
        "type": "string",
        "description": "A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.",
        "maxLength": 1024
      },
      "code": {
        "type": "string",
        "description": "An API specific error code aiding the provider team understand the error based on their own potential taxonomy or registry.",
        "maxLength": 50
      },
      "errors": {
        "type": "array",
        "description": "An array of error details to accompany a problem details response.",
        "maxItems": 1000,
        "items": {
          "type": "object",
          "description": "An object to provide explicit details on a problem towards an API consumer.",
          "properties": {
            "detail": {
              "type": "string",
              "description": "A granular description on the specific error related to a body property, query parameter, path parameters, and/or header.",
              "maxLength": 4096
            },
            "pointer": {
              "type": "string",
              "description": "A JSON Pointer to a specific request body property that is the source of error.",
              "maxLength": 1024
            },
            "parameter": {
              "type": "string",
              "description": "The name of the query or path parameter that is the source of error.",
              "maxLength": 1024
            },
            "header": {
              "type": "string",
              "description": "The name of the header that is the source of error.",
              "maxLength": 1024
            },
            "code": {
              "type": "string",
              "description": "A string containing additional provider specific codes to identify the error context.",
              "maxLength": 50
            }
          },
          "required": [
            "detail"
          ]
        }
      }
    },
    "required": [
      "detail"
    ]
  }