{"id":50785534,"url":"https://github.com/hmlendea/nuciapi.middleware.exceptionhandling","last_synced_at":"2026-06-12T07:30:42.615Z","repository":{"id":354021584,"uuid":"1221734859","full_name":"hmlendea/nuciapi.middleware.exceptionhandling","owner":"hmlendea","description":"ASP.NET Core middleware that translates common runtime exceptions into consistent NuciAPI error responses.","archived":false,"fork":false,"pushed_at":"2026-04-26T18:25:09.000Z","size":33,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-04-26T20:25:46.453Z","etag":null,"topics":["api","csharp","dotnet","library","nuget","nuget-package","rest","rest-api"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hmlendea.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"hmlendea","patreon":"hmlendea","open_collective":null,"ko_fi":"hmlendea","tidelift":null,"community_bridge":null,"liberapay":"HMlendea","issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":"hmlendea","thanks_dev":null,"custom":"https://hmlendea.go.ro/fund.html"}},"created_at":"2026-04-26T16:03:27.000Z","updated_at":"2026-04-26T18:28:22.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/hmlendea/nuciapi.middleware.exceptionhandling","commit_stats":null,"previous_names":["hmlendea/nuciapi.middleware.exceptionhandling"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/hmlendea/nuciapi.middleware.exceptionhandling","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hmlendea%2Fnuciapi.middleware.exceptionhandling","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hmlendea%2Fnuciapi.middleware.exceptionhandling/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hmlendea%2Fnuciapi.middleware.exceptionhandling/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hmlendea%2Fnuciapi.middleware.exceptionhandling/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hmlendea","download_url":"https://codeload.github.com/hmlendea/nuciapi.middleware.exceptionhandling/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hmlendea%2Fnuciapi.middleware.exceptionhandling/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34234557,"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-12T02:00:06.859Z","response_time":109,"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":["api","csharp","dotnet","library","nuget","nuget-package","rest","rest-api"],"created_at":"2026-06-12T07:30:42.026Z","updated_at":"2026-06-12T07:30:42.598Z","avatar_url":"https://github.com/hmlendea.png","language":"C#","funding_links":["https://github.com/sponsors/hmlendea","https://patreon.com/hmlendea","https://ko-fi.com/hmlendea","https://liberapay.com/HMlendea","https://buymeacoffee.com/hmlendea","https://hmlendea.go.ro/fund.html"],"categories":[],"sub_categories":[],"readme":"[![Donate](https://img.shields.io/badge/-%E2%99%A5%20Donate-%23ff69b4)](https://hmlendea.go.ro/fund.html)\n[![Latest Release](https://img.shields.io/github/v/release/hmlendea/nuciapi.middleware.exceptionhandling)](https://github.com/hmlendea/nuciapi.middleware.exceptionhandling/releases/latest)\n[![Build Status](https://github.com/hmlendea/nuciapi.middleware.exceptionhandling/actions/workflows/dotnet.yml/badge.svg)](https://github.com/hmlendea/nuciapi.middleware.exceptionhandling/actions/workflows/dotnet.yml)\n[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://gnu.org/licenses/gpl-3.0)\n\n# NuciAPI.Middleware.ExceptionHandling\n\nASP.NET Core middleware that translates common runtime exceptions into consistent JSON API error responses.\n\nIt is intended for NuciAPI-based services and integrates directly in the request pipeline through a single extension method.\n\n## Installation\n\n[![Get it from NuGet](https://raw.githubusercontent.com/hmlendea/readme-assets/master/badges/stores/nuget.png)](https://nuget.org/packages/NuciAPI.Middleware.ExceptionHandling)\n\n### .NET CLI\n\n```bash\ndotnet add package NuciAPI.Middleware.ExceptionHandling\n```\n\n### Package Manager\n\n```powershell\nInstall-Package NuciAPI.Middleware.ExceptionHandling\n```\n\n## Requirements\n\n- .NET SDK/runtime with support for `net10.0`\n- ASP.NET Core (`Microsoft.AspNetCore.App`)\n\n## What This Package Includes\n\n- `UseNuciApiExceptionHandling()` extension method for `IApplicationBuilder`\n- Exception handling middleware that:\n\t- catches known exception categories\n\t- maps them to HTTP status codes\n\t- writes JSON error payloads (`application/json`)\n\n## Quick Start\n\nRegister the middleware in your application startup pipeline.\n\n### Minimal API (Program.cs)\n\n```csharp\nusing NuciAPI.Middleware.ExceptionHandling;\n\nWebApplicationBuilder builder = WebApplication.CreateBuilder(args);\nWebApplication app = builder.Build();\n\napp.UseNuciApiExceptionHandling();\n\napp.MapGet(\"/\", () =\u003e \"OK\");\n\napp.Run();\n```\n\n### ASP.NET Core Startup class\n\n```csharp\nusing NuciAPI.Middleware.ExceptionHandling;\n\npublic class Startup\n{\n    public void Configure(IApplicationBuilder app)\n    {\n        app.UseNuciApiExceptionHandling();\n\n        // Other middleware/components\n    }\n}\n```\n\n## Exception Mapping\n\nThe middleware currently maps the following exceptions:\n\n| Exception type(s) | HTTP status | Error response |\n| --- | --- | --- |\n| `BadHttpRequestException`, `FormatException`, `ArgumentException`, `ValidationException` | 400 Bad Request | `NuciApiErrorResponse` with exception message and bad-request code |\n| `SecurityException`, `UnauthorizedAccessException` | 403 Forbidden | `NuciApiErrorResponse.Unauthorised` |\n| `HttpRequestException`, `TaskCanceledException`, `TimeoutException` | 503 Service Unavailable | `NuciApiErrorResponse.ServiceDependencyUnavailable` |\n| `AuthenticationException` | 401 Unauthorized | `NuciApiErrorResponse.AuthenticationFailure` |\n| `EntityNotFoundException`, `KeyNotFoundException` | 404 Not Found | `NuciApiErrorResponse.NotFound` |\n| `RequestAlreadyProcessedException` | 409 Conflict | `NuciApiErrorResponse.AlreadyExists` or explicit already-processed response |\n| `NotImplementedException` | 501 Not Implemented | `NuciApiErrorResponse` with not-implemented code |\n| `OperationCanceledException` | 499 Client Closed Request | `NuciApiErrorResponse.ClientClosedTheRequest` |\n| Any other unhandled exception | 500 Internal Server Error | `NuciApiErrorResponse.InternalServerError` |\n\n## Response Format\n\nResponses are written as JSON and use the error response types from `NuciAPI.Responses`.\n\nThe middleware sets:\n\n- status code according to the mapping table\n- `Content-Type: application/json`\n\n## Notes\n\n- Register this middleware early enough in the pipeline to capture downstream exceptions.\n- The middleware converts exceptions to HTTP responses and prevents unhandled exceptions from propagating further.\n- For cancellations, client-aborted requests are represented as HTTP 499.\n\n\n## Development\n\n### Build\n\n```bash\ndotnet build NuciAPI.Middleware.ExceptionHandling.sln\n```\n\n### Test\n\n```bash\ndotnet test NuciAPI.Middleware.ExceptionHandling.sln\n```\n\n### Pack\n\n```bash\ndotnet pack -c Release\n```\n\n## Contributing\n\nContributions are welcome.\n\nPlease:\n\n- keep the changes cross-platform\n- keep the pull requests focused and consistent with the existing style\n- update the documentation when the behaviour changes\n- add or update the tests for any new behaviour\n\n## Related Projects\n\n- [NuciAPI.Middleware](https://github.com/hmlendea/nuciapi.middleware)\n- [NuciAPI.Middleware.ExceptionHandling](https://github.com/hmlendea/nuciapi.middleware.exceptionhandling)\n- [NuciAPI.Middleware.Logging](https://github.com/hmlendea/nuciapi.middleware.logging)\n- [NuciAPI.Middleware.Security](https://github.com/hmlendea/nuciapi.middleware.security)\n\n## License\n\nLicensed under the GNU General Public License v3.0 or later.\nSee [LICENSE](./LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhmlendea%2Fnuciapi.middleware.exceptionhandling","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhmlendea%2Fnuciapi.middleware.exceptionhandling","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhmlendea%2Fnuciapi.middleware.exceptionhandling/lists"}