EOAP Problem Details Registry

This registry acts as a well-known location for problem detail types returned by various EOAP APIs. It acts as a central registry to promote reuse and clarity of problem detail types conforming to RFC 9457, formerly RFC 7807.

EOAP Problem Types

Common Problem Types

The following types can also be leveraged for convenience; however, the recommendation is to utilize the IANA registry for generic/common types.

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 JSON Schema defined in our GitHub repo.

Python Usage

Install the package in an environment with Pydantic 2:

pip install eoap-problems-registry

Use the generated models to build responses with fixed registry fields and optional extension members:

import eoap_problems_registry as registry

problem = registry.MissingRequestParameter(
    instance="https://api.example.test/problems/abc123",
    code="400-03",
    errors=[
        registry.ErrorDetail(
            detail="The query parameter limit is required.",
            parameter="limit",
        )
    ],
)

payload = problem.model_dump(mode="json", exclude_none=True)

The resulting payload includes the registered type, status, title, and detail values:

{
  "instance": "https://api.example.test/problems/abc123",
  "code": "400-03",
  "errors": [
    {
      "detail": "The query parameter limit is required.",
      "parameter": "limit"
    }
  ],
  "type": "https://eoap.github.io/problems-registry/missing-request-parameter",
  "status": 400,
  "title": "Missing request parameter",
  "detail": "The request is missing an expected query or path parameter.",
}

ProblemDetails and ErrorDetail allow additional provider-specific fields, while generated problem classes use Pydantic literal fields to protect the registered type, status, title, and detail values.

FastAPI Integration

The optional FastAPI integration requires Python 3.10 or newer. Install it with the fastapi extra:

pip install "eoap-problems-registry[fastapi]"

Register an exception handler that returns the problem detail as the response body, then raise ProblemRegistryException from a route:

from fastapi import FastAPI

import eoap_problems_registry as registry
from eoap_problems_registry.fastapi import ProblemRegistryException

app = FastAPI()


@app.get("/resources/{resource_id}")
async def get_resource(resource_id: str) -> dict[str, str]:
    raise ProblemRegistryException(
        problem=registry.NotFound(
            instance=f"https://api.example.test/resources/{resource_id}",
        )
    )