{"id":"c104959419c82ea7","repo":"pallets/flask","slug":"exc-class-or-code-is-not-a-recognized-http-err","errorCode":null,"errorMessage":"'{exc_class_or_code}' is not a recognized HTTP error code. Use a subclass of HTTPException with that code instead.","messagePattern":"'(.+?)' is not a recognized HTTP error code\\. Use a subclass of HTTPException with that code instead\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/flask/sansio/scaffold.py","lineNumber":673,"sourceCode":"\n    @staticmethod\n    def _get_exc_class_and_code(\n        exc_class_or_code: type[Exception] | int,\n    ) -> tuple[type[Exception], int | None]:\n        \"\"\"Get the exception class being handled. For HTTP status codes\n        or ``HTTPException`` subclasses, return both the exception and\n        status code.\n\n        :param exc_class_or_code: Any exception class, or an HTTP status\n            code as an integer.\n        \"\"\"\n        exc_class: type[Exception]\n\n        if isinstance(exc_class_or_code, int):\n            try:\n                exc_class = default_exceptions[exc_class_or_code]\n            except KeyError:\n                raise ValueError(\n                    f\"'{exc_class_or_code}' is not a recognized HTTP\"\n                    \" error code. Use a subclass of HTTPException with\"\n                    \" that code instead.\"\n                ) from None\n        else:\n            exc_class = exc_class_or_code\n\n        if isinstance(exc_class, Exception):\n            raise TypeError(\n                f\"{exc_class!r} is an instance, not a class. Handlers\"\n                \" can only be registered for Exception classes or HTTP\"\n                \" error codes.\"\n            )\n\n        if not issubclass(exc_class, Exception):\n            raise ValueError(\n                f\"'{exc_class.__name__}' is not a subclass of Exception.\"\n                \" Handlers can only be registered for Exception classes\"","sourceCodeStart":655,"sourceCodeEnd":691,"githubUrl":"https://github.com/pallets/flask/blob/6a2f545bfd8ed31e19066a299296917e034aca58/src/flask/sansio/scaffold.py#L655-L691","documentation":"When you register an error handler with an integer code, Flask looks it up in Werkzeug's default_exceptions mapping to find the corresponding HTTPException class. Only standard HTTP error codes with a registered exception class exist there; an unknown integer (like 200, 250, or a custom 4xx) raises this ValueError from _get_exc_class_and_code.","triggerScenarios":"@app.errorhandler(code) or app.register_error_handler(code, fn) with an int not in werkzeug.exceptions.default_exceptions — e.g. 200, 302 (non-error), 420, 444, or a proprietary code.","commonSituations":"Trying to hook non-error statuses (2xx/3xx) with errorhandler; using nginx/Cloudflare-specific codes (444, 520); expecting arbitrary custom status codes to work without defining an exception class.","solutions":["Use a recognized HTTP error code (one that has a Werkzeug HTTPException, e.g. 404, 500).","For a custom code, subclass werkzeug.exceptions.HTTPException with code = <n> and register the handler for that class.","For non-error statuses, use an after_request hook instead of an error handler."],"exampleFix":"# before\n@app.errorhandler(420)\ndef handle(e): ...\n# after\nfrom werkzeug.exceptions import HTTPException\nclass EnhanceYourCalm(HTTPException):\n    code = 420\n    description = 'Enhance your calm.'\n@app.errorhandler(EnhanceYourCalm)\ndef handle(e): ...","handlingStrategy":"validation","validationCode":"from werkzeug.exceptions import default_exceptions\ncode = 404\nif code not in default_exceptions:\n    raise ValueError(f\"{code} is not a standard HTTP error code; register a custom HTTPException subclass instead\")\napp.register_error_handler(code, handler)","typeGuard":"from werkzeug.exceptions import default_exceptions\ndef is_registrable_code(code) -> bool:\n    return isinstance(code, int) and code in default_exceptions","tryCatchPattern":null,"preventionTips":["Only register int handlers for codes Werkzeug knows (werkzeug.exceptions.default_exceptions)","For nonstandard codes, define a subclass of HTTPException with that code and register the class","Keep error-handler registration in one module so codes are easy to audit"],"tags":["flask","error-handling","http-status"],"analyzedSha":"6a2f545bfd8ed31e19066a299296917e034aca58","analyzedAt":"2026-07-31T19:13:49.921Z","schemaVersion":2}