{"id":18408352,"url":"https://github.com/pingcap/errcode","last_synced_at":"2026-04-02T16:03:56.075Z","repository":{"id":57483571,"uuid":"149691020","full_name":"pingcap/errcode","owner":"pingcap","description":null,"archived":false,"fork":false,"pushed_at":"2023-11-02T07:39:06.000Z","size":178,"stargazers_count":16,"open_issues_count":0,"forks_count":7,"subscribers_count":110,"default_branch":"master","last_synced_at":"2025-03-22T16:02:13.096Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pingcap.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":"2018-09-21T01:13:57.000Z","updated_at":"2025-01-22T16:30:58.000Z","dependencies_parsed_at":"2024-06-18T17:06:12.166Z","dependency_job_id":null,"html_url":"https://github.com/pingcap/errcode","commit_stats":{"total_commits":25,"total_committers":3,"mean_commits":8.333333333333334,"dds":0.07999999999999996,"last_synced_commit":"4d6d0ddd9c6f2eb2cc803acf7cd0aeb8df50b33a"},"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pingcap%2Ferrcode","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pingcap%2Ferrcode/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pingcap%2Ferrcode/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pingcap%2Ferrcode/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pingcap","download_url":"https://codeload.github.com/pingcap/errcode/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247620889,"owners_count":20968311,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":[],"created_at":"2024-11-06T03:18:39.971Z","updated_at":"2026-04-02T16:03:56.032Z","avatar_url":"https://github.com/pingcap.png","language":"Go","readme":"## About Error codes\n\nError codes reliably communicate the error type, particularly across program (network) boundaries.\nA program can reliably respond to an error if it can be sure to understand its type.\nError monitoring systems can reliably understand what errors are occurring.\n\n## status\n\nThis library is in a completed state.\nIt should be updated now though for some of the changes to golang for error wrapping.\n\n# errcode overview\n\nThis package extends go errors via interfaces to have error codes.\nThe two main goals are\n\n  * The clients can reliably understand errors by checking against error codes.\n  * Structure information is sent to the client\n\nSee the [go docs](https://godoc.org/github.com/pingcap/errcode) for extensive API documentation.\n\nThere are other packages that add error code capabilities to errors.\nHowever, they almost universally use a single underlying error struct.\nA code or other annotation is a field on that struct.\nIn most cases a structured error response is only possible to create dynamically via tags and labels.\n\nerrcode instead follows the model of pkg/errors to use wrapping and interfaces.\nYou are encouraged to make your own error structures and then fulfill the ErrorCode interface by adding a function.\nAdditional features (for example annotating the operation) are done via wrapping.\n\nThis design makes errcode highly extensible, inter-operable, and structure preserving (of the original error).\nIt is easy to gradually introduce it into a project that is using pkg/errors (or the Cause interface).\n\n\n## Features\n\n* structured error representation\n* Follows the pkg/errors model where error enhancements are annotations via the Causer interface.\n* Internal errors show a stack trace but others don't.\n* Operation annotation. This concept is [explained here](https://commandcenter.blogspot.com/2017/12/error-handling-in-upspin.html).\n* Works for multiple errors when the Errors() interface is used. See the `Combine` function for constructing multiple error codes.\n* Extensible metadata. See how SetHTTPCode is implemented.\n* Integration with existing error codes\n  * HTTP\n  * GRPC (provided by separate grpc package)\n\n\n## Example\n\n\n``` go\n// First define a normal error type\ntype PathBlocked struct {\n\tstart     uint64 `json:\"start\"`\n\tend       uint64 `json:\"end\"`\n\tobstacle  uint64 `json:\"end\"`\n}\n\nfunc (e PathBlocked) Error() string {\n\treturn fmt.Sprintf(\"The path %d -\u003e %d has obstacle %d\", e.start, e.end, e.obstacle)\n}\n\n// Define a code. These often get re-used between different errors.\n// Note that codes use a hierarchy to share metadata.\n// This code is a child of the \"state\" code.\nvar PathBlockedCode = errcode.StateCode.Child(\"state.blocked\")\n\n// Now attach the code to your custom error type.\nfunc (e PathBlocked) Code() Code {\n\treturn PathBlockedCode\n}\n\nvar _ ErrorCode = (*PathBlocked)(nil)  // assert implements the ErrorCode interface\n```\n\nNow lets see how you can send the error code to a client in a way that works with your exising code.\n\n``` go\n// Given just a type of error, give an error code to a client if it is present\nif errCode := errcode.CodeChain(err); errCode != nil {\n\t// If it helps, you can set the code a header\n\tw.Header().Set(\"X-Error-Code\", errCode.Code().CodeStr().String())\n\n\t// But the code will also be in the JSON body\n\t// Codes have HTTP codes attached as meta data.\n\t// You can also attach other kinds of meta data to codes.\n\t// Our error code inherits StatusBadRequest from its parent code \"state\"\n\trd.JSON(w, errCode.Code().HTTPCode(), errcode.NewJSONFormat(errCode))\n}\n```\n\nLet see a usage site. This example will include an annotation concept of \"operation\".\n\n``` go\nfunc moveX(start, end, obstacle) error {}\n\top := errcode.Op(\"path.move.x\")\n\n\tif start \u003c obstable \u0026\u0026 obstacle \u003c end  {\n\t\treturn op.AddTo(PathBlocked{start, end, obstacle})\n\t}\n}\n```\n\n\n## Development\n\n``` shell\n./scripts/build\n./scripts/test\n./scripts/check\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpingcap%2Ferrcode","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpingcap%2Ferrcode","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpingcap%2Ferrcode/lists"}