pallets/flask · error · ValueError

' ' is not a recognized HTTP error code. Use a subclass of…

Error message

'{exc_class_or_code}' is not a recognized HTTP error code. Use a subclass of HTTPException with that code instead.

What it means

_register_error_handler looks up integer codes in Werkzeug's default_exceptions map (which only contains the standard HTTP error codes 400-418, 421-426, 428-431, 444, 449, 451, 455-456, 500-508, 510-511). An integer outside that set raises ValueError suggesting a subclass of HTTPException instead.

Solutions

Define a custom HTTPException subclass with .code set to your code, and register that class instead of the integer.
Use a standard HTTP error code that Werkzeug knows.
Register the handler against HTTPException generally if you want to catch all HTTP errors.

Example fix

// before
@app.errorhandler(520)
def handle_520(e): return 'oops', 520

// after
from werkzeug.exceptions import HTTPException
class Err520(HTTPException):
    code = 520

@app.errorhandler(Err520)
def handle_520(e): return 'oops', 520

Defensive patterns

Strategy: validation

Validate before calling

from werkzeug.exceptions import default_exceptions

def validate_error_code(code: int) -> int:
    if code not in default_exceptions:
        raise ValueError(f'{code} is not a known HTTP error code; subclass HTTPException')
    return code

Type guard

def is_known_http_error_code(code) -> bool:
    return isinstance(code, int) and code in default_exceptions

Prevention

Register handlers against known codes or HTTPException subclasses, not arbitrary ints.
Create a custom HTTPException subclass for app-specific codes.
Keep a constant list of supported codes for config-driven handlers.

When it happens

Trigger: Calling @app.errorhandler(999); @app.errorhandler(200); @app.errorhandler(419) or any non-standard code; passing a custom status code integer that has no default exception class.

Common situations: Using a custom non-RFC status code; typos in the code; app-specific codes like 460/520 that Werkzeug does not ship.

Related errors

AI-assisted analysis of pallets/flask@3596b1ab61 (2026-08-11). Data as JSON: /api/errors/c104959419c82ea7. Report an issue: GitHub.

Appendix: source

Thrown at src/flask/sansio/scaffold.py:673

    @staticmethod
    def _get_exc_class_and_code(
        exc_class_or_code: type[Exception] | int,
    ) -> tuple[type[Exception], int | None]:
        """Get the exception class being handled. For HTTP status codes
        or ``HTTPException`` subclasses, return both the exception and
        status code.

        :param exc_class_or_code: Any exception class, or an HTTP status
            code as an integer.
        """
        exc_class: type[Exception]

        if isinstance(exc_class_or_code, int):
            try:
                exc_class = default_exceptions[exc_class_or_code]
            except KeyError:
                raise ValueError(
                    f"'{exc_class_or_code}' is not a recognized HTTP"
                    " error code. Use a subclass of HTTPException with"
                    " that code instead."
                ) from None
        else:
            exc_class = exc_class_or_code

        if isinstance(exc_class, Exception):
            raise TypeError(
                f"{exc_class!r} is an instance, not a class. Handlers"
                " can only be registered for Exception classes or HTTP"
                " error codes."
            )

        if not issubclass(exc_class, Exception):
            raise ValueError(
                f"'{exc_class.__name__}' is not a subclass of Exception."
                " Handlers can only be registered for Exception classes"

View on GitHub (pinned to 3596b1ab61)