presentation.routers.api.v1.errors.problem_details

src.presentation.routers.api.v1.errors.problem_details

RFC 9457 Problem Details for HTTP APIs.

This module implements RFC 9457 (Problem Details for HTTP APIs) using Pydantic models for structured error responses.

RFC 9457: https://www.rfc-editor.org/rfc/rfc9457.html

Exports

ErrorDetail: Individual field-specific error ProblemDetails: RFC 9457 compliant error response schema

Classes

ErrorDetail

Bases: BaseModel

Individual field-specific error.

Used for validation errors where multiple fields may have errors.

Attributes:

Name	Type	Description
field	str	Name of the field with error
code	str	Machine-readable error code
message	str	Human-readable error message

Examples:

>>> error = ErrorDetail(
...     field="email",
...     code="invalid_email",
...     message="Email address format is invalid",
... )

Source code in src/presentation/routers/api/v1/errors/problem_details.py

class ErrorDetail(BaseModel):
    """Individual field-specific error.

    Used for validation errors where multiple fields may have errors.

    Attributes:
        field: Name of the field with error
        code: Machine-readable error code
        message: Human-readable error message

    Examples:
        >>> error = ErrorDetail(
        ...     field="email",
        ...     code="invalid_email",
        ...     message="Email address format is invalid",
        ... )
    """

    field: str = Field(..., description="Field name")
    code: str = Field(..., description="Machine-readable error code")
    message: str = Field(..., description="Human-readable error message")

ProblemDetails

Bases: BaseModel

RFC 9457 Problem Details for HTTP APIs.

Standard error response format providing structured information about errors in HTTP APIs. All fields follow RFC 9457 specification.

Attributes:

Name	Type	Description
type	str	URI reference identifying the problem type
title	str	Short, human-readable summary of the problem type
status	int	HTTP status code for this occurrence
detail	str	Human-readable explanation specific to this occurrence
instance	str	URI reference identifying the specific occurrence
errors	list[ErrorDetail] | None	Optional list of field-specific errors (for validation failures)
trace_id	str | None	Optional request trace ID for debugging

Examples:

>>> # Validation error
>>> problem = ProblemDetails(
...     type="https://api.dashtam.com/errors/validation-error",
...     title="Validation Failed",
...     status=400,
...     detail="The email address format is invalid",
...     instance="/api/v1/auth/register",
...     errors=[
...         ErrorDetail(
...             field="email",
...             code="invalid_email",
...             message="Email address format is invalid",
...         )
...     ],
...     trace_id="550e8400-e29b-41d4-a716-446655440000",
... )
>>>
>>> # Not found error
>>> problem = ProblemDetails(
...     type="https://api.dashtam.com/errors/not-found",
...     title="Resource Not Found",
...     status=404,
...     detail="User with ID '123' does not exist",
...     instance="/api/v1/users/123",
...     trace_id="550e8400-e29b-41d4-a716-446655440000",
... )

Source code in src/presentation/routers/api/v1/errors/problem_details.py

class ProblemDetails(BaseModel):
    """RFC 9457 Problem Details for HTTP APIs.

    Standard error response format providing structured information about errors
    in HTTP APIs. All fields follow RFC 9457 specification.

    Attributes:
        type: URI reference identifying the problem type
        title: Short, human-readable summary of the problem type
        status: HTTP status code for this occurrence
        detail: Human-readable explanation specific to this occurrence
        instance: URI reference identifying the specific occurrence
        errors: Optional list of field-specific errors (for validation failures)
        trace_id: Optional request trace ID for debugging

    Examples:
        >>> # Validation error
        >>> problem = ProblemDetails(
        ...     type="https://api.dashtam.com/errors/validation-error",
        ...     title="Validation Failed",
        ...     status=400,
        ...     detail="The email address format is invalid",
        ...     instance="/api/v1/auth/register",
        ...     errors=[
        ...         ErrorDetail(
        ...             field="email",
        ...             code="invalid_email",
        ...             message="Email address format is invalid",
        ...         )
        ...     ],
        ...     trace_id="550e8400-e29b-41d4-a716-446655440000",
        ... )
        >>>
        >>> # Not found error
        >>> problem = ProblemDetails(
        ...     type="https://api.dashtam.com/errors/not-found",
        ...     title="Resource Not Found",
        ...     status=404,
        ...     detail="User with ID '123' does not exist",
        ...     instance="/api/v1/users/123",
        ...     trace_id="550e8400-e29b-41d4-a716-446655440000",
        ... )
    """

    type: str = Field(
        ...,
        description="URI reference identifying the problem type",
        examples=["https://api.dashtam.com/errors/validation-error"],
    )
    title: str = Field(
        ...,
        description="Short, human-readable summary",
        examples=["Validation Failed"],
    )
    status: int = Field(
        ...,
        description="HTTP status code",
        examples=[400],
    )
    detail: str = Field(
        ...,
        description="Human-readable explanation",
        examples=["The email address format is invalid"],
    )
    instance: str = Field(
        ...,
        description="URI reference identifying this occurrence",
        examples=["/api/v1/auth/register"],
    )
    errors: list[ErrorDetail] | None = Field(
        None,
        description="List of field-specific errors",
    )
    trace_id: str | None = Field(
        None,
        description="Request trace ID for debugging",
    )