{"id":42899357,"url":"https://github.com/carlosupreme/problem-details-http","last_synced_at":"2026-01-30T15:20:05.832Z","repository":{"id":214825072,"uuid":"736489778","full_name":"carlosupreme/problem-details-http","owner":"carlosupreme","description":"TypeScript implementation of the RFC 7807 standard.","archived":false,"fork":false,"pushed_at":"2024-08-12T02:22:30.000Z","size":72,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-09T13:39:01.040Z","etag":null,"topics":["http","problem-details","rfc-7807","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/carlosupreme.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":"2023-12-28T03:46:58.000Z","updated_at":"2024-08-12T02:22:33.000Z","dependencies_parsed_at":null,"dependency_job_id":"2cf85cf1-2e83-4de8-ac09-48e40a88a95f","html_url":"https://github.com/carlosupreme/problem-details-http","commit_stats":{"total_commits":6,"total_committers":2,"mean_commits":3.0,"dds":"0.16666666666666663","last_synced_commit":"95435bebbb9ac4d7ef484d81ad311c1ba7f64235"},"previous_names":["carlosupreme/problem-details-http"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/carlosupreme/problem-details-http","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carlosupreme%2Fproblem-details-http","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carlosupreme%2Fproblem-details-http/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carlosupreme%2Fproblem-details-http/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carlosupreme%2Fproblem-details-http/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/carlosupreme","download_url":"https://codeload.github.com/carlosupreme/problem-details-http/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carlosupreme%2Fproblem-details-http/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28914902,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-30T12:13:43.263Z","status":"ssl_error","status_checked_at":"2026-01-30T12:13:22.389Z","response_time":66,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["http","problem-details","rfc-7807","typescript"],"created_at":"2026-01-30T15:20:05.767Z","updated_at":"2026-01-30T15:20:05.825Z","avatar_url":"https://github.com/carlosupreme.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\" \u003e\n\n# `problem-details-http`\n\n[![NPM Version](https://badgen.net/npm/v/problem-details-http?color=red)](https://www.npmjs.com/package/problem-details-http)\n![License](https://badgen.net/npm/license/problem-details-http?color=yellow)\n![Last Commit](https://badgen.net/github/last-commit/carlosupreme/problem-details-http/main?color=blue\u0026icon=github)\n\n![Open Issues](https://badgen.net/github/open-issues/carlosupreme/problem-details-http?color=green\u0026icon=github)\n![Dependencies](https://badgen.net/badge/dependencies/none/green)\n[![GZIP Size](https://img.badgesize.io/https://unpkg.com/problem-details-http@latest/dist/index.js?compression=gzip)](https://unpkg.com/problem-details-http@latest/dist/index.js)\n\u003c/div\u003e\n\n\n## Overview\n\nWelcome to the documentation for the **HTTP Problem Details Library**. This library is designed to facilitate the implementation of the HTTP Problem Details convention as specified in [RFC 7807](https://tools.ietf.org/html/rfc7807). The library helps you structure and return error responses in a consistent and standardized format.\n\n## Installation\n\nTo use this library in your project, you can install it via [npm](https://www.npmjs.com/). Run the following command in your project directory:\n\n```bash\nnpm install problem-details-http\n```\n\n## Intro\n\nA problem details object looks like this:\n\n```json\n{\n  \"type\": \"https://example.com/probs/out-of-credit\",\n  \"status\": 403,\n  \"title\": \"You do not have enough credit.\",\n  \"detail\": \"Your current balance is 30, but that costs 50.\",\n  \"instance\": \"/account/12345/msgs/abc\"\n}\n```\n\nWhen the members are:\n\n- **type** (string): URI to the explanation of the error type\n- **status** (number): HTTP status code\n- **title** (string): Short description of the error\n- **detail** (string): Specific explanation of the error\n- **instance** (string) (optional): URI to some instance where the error ocurred\n\nThis object also allows to store member extensions, e.g :\n\n```json\n{\n  \"type\": \"https://example.com/probs/out-of-credit\",\n  \"status\": 403,\n  \"title\": \"You do not have enough credit.\",\n  \"detail\": \"Your current balance is 30, but that costs 50.\",\n  \"instance\": \"/account/12345/msgs/abc\",\n  \"balance\": 30,\n  \"accounts\": [\"/account/12345\", \"/account/67890\"]\n}\n```\n\n```json\n{\n  \"type\": \"https://example.net/validation-error\",\n  \"status\": 422,\n  \"title\": \"Your request is not valid.\",\n  \"detail\": \"The are some validation errors in your request\",\n  \"errors\": [\n    {\n      \"detail\": \"must be a positive integer\",\n      \"pointer\": \"#/age\"\n    },\n    {\n      \"detail\": \"must be 'green', 'red' or 'blue'\",\n      \"pointer\": \"#/profile/color\"\n    }\n  ]\n}\n```\n\n## Usage\n\n### Importing the Library\n\nIn your project, import the library as follows:\n\n```js\nimport { PDBuilder } from \"problem-details-http\";\n```\n\n### Creating a Problem Details Object\n\nTo create a Problem Details object, you can use the `fromDetail` function, followed by the methods that are named the same as the members established in the document, this method is named `fromDetail` because the \"detail\" member should be the only required member that your application must specifically provide.\n\n```js\nconst problemDetails = PDBuilder.fromDetail(\"This is an example error message.\")\n  .type(\"https://example.com/error\")\n  .title(\"Example Error\")\n  .status(400)\n  .instance(\"URI/to/the/instance\")\n  .build();\n```\n\nAnd this will create an object like this:\n\n```json\n{\n  \"type\": \"https://example.com/error\",\n  \"status\": 400,\n  \"title\": \"Example Error\",\n  \"detail\": \"This is an example error message.\",\n  \"instance\": \"URI/to/the/instance\"\n}\n```\n\n### Creating a Problem Details Object With Default Http Data\n\nThis library provides default values for all http errors in case you do not have a specific URI for your error type or u prefer to use generic titles.\n\n```js\nconst problemDetails = PDBuilder.fromDetail(\n  \"This is an example error message.\"\n).build();\n```\n\nAnd this will create an object like the following one, 400 is the default status code:\n\n```json\n{\n  \"type\": \"https://datatracker.ietf.org/doc/html/rfc7231#section-6.5.1\",\n  \"status\": 400,\n  \"title\": \"Bad Request\",\n  \"detail\": \"This is an example error message.\"\n}\n```\n\n### Returning Problem Details as JSON\n\nYou can then return the Problem Details object as a JSON response in your HTTP endpoint:\n\n```js\nres.status(problemDetails.status).json(problemDetails);\n```\n\n### Handling Errors\n\nWhen an error occurs in your application, use the library to create and return a Problem Details object. This ensures that error responses adhere to the RFC 7807 standard. You can take advantage of the Error instance using the `PDBuilder`, it takes the `constructor.name` as the title, and the `message` property as the detail member\n\n```js\n// OutOfCreditError.ts\nexport class OutOfCreditError extends Error {}\n```\n\n```js\n// exampleController.ts\ntry {\n  // some code\n  if (something.goesWrong()) {\n    throw new OutOfCreditError(\n      `Your current balance is ${current}, but that costs ${price}.`\n    );\n  }\n} catch (error) {\n  if (error instanceof OutOfCreditError) {\n    const problemDetails = PDBuilder.fromError(error)\n      .status403()\n      .type(\"https://example.com/probs/out-of-credit\")\n      .instance(\"URI/to/the/instance\")\n      .extensions({\n        balance: 30,\n        accounts: [\"/account/12345\", \"/account/67890\"],\n      });\n\n    res.status(problemDetails.status).json(problemDetails);\n  }\n}\n```\n\nResponse of the api endpoint\n\n```\nHTTP/1.1 403 Forbidden\nContent-Type: application/problem+json\n```\n\n```json\n{\n  \"type\": \"https://example.com/probs/out-of-credit\",\n  \"title\": \"Out of credit\",\n  \"status\": 403,\n  \"detail\": \"Your current balance is 30, but that costs 50.\",\n  \"instance\": \"URI/to/the/instance\",\n  \"balance\": 30,\n  \"accounts\": [\"/account/12345\", \"/account/67890\"]\n}\n```\n\n## Contributing\n\nWe welcome contributions to improve and expand this library. If you encounter issues or have suggestions, please open an [issue](https://github.com/carlosupreme/problem-details-http/issues) or submit a [pull request](https://github.com/carlosupreme/problem-details-http/pulls) on our GitHub repository.\n\n## License\n\nThis library is distributed under the [MIT License](LICENSE). Feel free to use, modify, and distribute it as needed.\n\nThank you for using the HTTP Problem Details Library!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcarlosupreme%2Fproblem-details-http","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcarlosupreme%2Fproblem-details-http","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcarlosupreme%2Fproblem-details-http/lists"}