{"id":51278726,"url":"https://github.com/patrsc/fastapi-simple-errors","last_synced_at":"2026-06-30T00:00:33.023Z","repository":{"id":257792011,"uuid":"861846543","full_name":"patrsc/fastapi-simple-errors","owner":"patrsc","description":"Simple error handling for fastapi using custom error classes.","archived":false,"fork":false,"pushed_at":"2024-10-25T13:23:15.000Z","size":106,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-21T04:29:43.475Z","etag":null,"topics":["fastapi","python","python3"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/patrsc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-09-23T15:55:59.000Z","updated_at":"2024-10-25T13:23:18.000Z","dependencies_parsed_at":null,"dependency_job_id":"75883830-7e26-4a44-b8f0-88fa1405e364","html_url":"https://github.com/patrsc/fastapi-simple-errors","commit_stats":null,"previous_names":["patrsc/fastapi-simple-errors"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/patrsc/fastapi-simple-errors","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patrsc%2Ffastapi-simple-errors","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patrsc%2Ffastapi-simple-errors/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patrsc%2Ffastapi-simple-errors/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patrsc%2Ffastapi-simple-errors/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/patrsc","download_url":"https://codeload.github.com/patrsc/fastapi-simple-errors/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patrsc%2Ffastapi-simple-errors/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34947088,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-29T02:00:05.398Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fastapi","python","python3"],"created_at":"2026-06-30T00:00:24.227Z","updated_at":"2026-06-30T00:00:32.932Z","avatar_url":"https://github.com/patrsc.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Tests](https://github.com/patrsc/fastapi-simple-errors/actions/workflows/tests.yml/badge.svg)](https://github.com/patrsc/fastapi-simple-errors/actions/workflows/tests.yml)\n[![Linting](https://github.com/patrsc/fastapi-simple-errors/actions/workflows/linting.yml/badge.svg)](https://github.com/patrsc/fastapi-simple-errors/actions/workflows/linting.yml)\n\n# fastapi-simple-errors\n\nSimple error handling for fastapi using custom error classes.\n\n## Introduction\n\nThis small Python package aims to simplify error handling for\n[FastAPI](https://fastapi.tiangolo.com/):\n* It allows defining custom exception classes in a simple way with little boilerplate code.\n* Your application functions can raise these errors and they will be propageted to FastAPI and\n  result in a proper 4xx or 5xx status code to be sent to the client.\n* Proper OpenAPI documentation can be generated using a generic response schema for errors, which includes the error ID (Python class name) and a human-readable error message.\n\nThis package was inspired by the following discussions and projects:\n* [Include possible HTTPExceptions in OpenAPI spec](https://github.com/tiangolo/fastapi/discussions/9124)\n* [FastAPI-Pydantic-Mongo_Sample_CRUD_API\n](https://github.com/David-Lor/FastAPI-Pydantic-Mongo_Sample_CRUD_API/tree/master)\n\n## Usage\n\nThe package [fastapi-simple-errors](https://pypi.org/project/fastapi-simple-errors/) is available\non [PyPi](https://pypi.org/), so it can be installed with Python package managers such as\n`pip` or [poetry](https://python-poetry.org/).\n\nFirst, you need to import the base errors from the package:\n\n```py\nfrom fastapi_simple_errors import BadRequestError, NotFoundError, UnauthorizedError\n```\n\nNow, you can define your custom errors based on you application's needs:\n\n```py\nclass UserNotFoundError(NotFoundError):\n    \"\"\"The user was not found in the database.\"\"\"\n\n\nclass InvalidUserIdError(BadRequestError):\n    \"\"\"The provided user ID is not valid.\"\"\"\n\n\nclass InvalidTokenError(UnauthorizedError):\n    \"\"\"The provided authentication token is not valid.\"\"\"\n\n```\n\nThese error's inherit from FastAPI's `HTTPException` and will use the corresponding HTTP status\ncodes, for example:\n* 400 for `BadRequestError`\n* 401 for `UnauthorizedError`\n* 404 for `NotFoundError`\n\nIn your FastAPI application, you could write:\n\n```py\n@app.get(\"/users/{user_id}\")\nasync def read_user(user_id: str):\n    if user_id not in users:\n        raise UserNotFoundError()\n    return {\"user\": users[user_id]}\n```\n\nNote that this error could also be raised in sub-functions and will be propagated accordingly.\n\nThis will result in the following response:\n\n```\nHTTP/1.1 404 Not Found\n...\n\n{\n    \"detail\": {\n        \"error\": \"UserNotFoundError\",\n        \"message\": \"The user was not found in the database.\"\n    }\n}\n```\n\nNote that the error class name is returned in the response as error identifier and the error\nmessage is used from the docstring. However, you could overwrite the message and also set custom\nheaders:\n\n```py\nraise UserNotFoundError(\"A custom message\", headers={\"X-State\": \"...\"})\n```\n\nThe predefined errors (like `NotFoundError`) all inherit from `AppError`.\nThis can be used to define your own errors with custom status codes, e.g.:\n\n```py\nfrom from fastapi_simple_errors import AppError\nfrom fastapi import status\n\nclass TeapotError(AppError):\n    \"\"\"This server is a teapot.\"\"\"\n\n    status_code = status.HTTP_418_IM_A_TEAPOT\n```\n\nTo include the errors (and error response schema) in the OpenAPI documentation,\nyou can use the package's `error_responses` function, like this:\n\n```py\nfrom fastapi_simple_errors import BadRequestError, NotFoundError, error_responses\n\n@app.get(\"/users/{user_id}\", responses=error_responses(BadRequestError, NotFoundError))\nasync def read_user(user_id: str):\n    if is_invalid(user_id):\n        raise InvalidUserIdError()\n    if user_id not in users:\n        raise UserNotFoundError()\n    return {\"user\": users[user_id]}\n```\n\nFor more concise code, you could alternatively use the `error_responses_from_status_codes` function:\n\n```py\nfrom fastapi_simple_errors import BadRequestError, NotFoundError\nfrom fastapi_simple_errors import error_responses_from_status_codes as err\n\n@app.get(\"/users/{user_id}\", responses=err(400, 404))\nasync def read_user(user_id: str):\n    if is_invalid(user_id):\n        raise InvalidUserIdError()\n    if user_id not in users:\n        raise UserNotFoundError()\n    return {\"user\": users[user_id]}\n```\n\nThe generated OpenAPI documentation will look like this (using [Redoc](https://redocly.com/redoc)):\n\n![openapi](https://raw.githubusercontent.com/patrsc/fastapi-simple-errors/main/openapi.png)\n\n## Licence\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpatrsc%2Ffastapi-simple-errors","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpatrsc%2Ffastapi-simple-errors","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpatrsc%2Ffastapi-simple-errors/lists"}