{"record":{"id":"8a8e78cc29ef59dc","repo":"grpc/grpc-go","slug":"invalid-code-d","errorCode":null,"errorMessage":"invalid code: %d","messagePattern":"invalid code: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"codes/codes.go","lineNumber":238,"sourceCode":"\t`\"DATA_LOSS\"`:           DataLoss,\n\t`\"UNAUTHENTICATED\"`:     Unauthenticated,\n}\n\n// UnmarshalJSON unmarshals b into the Code.\nfunc (c *Code) UnmarshalJSON(b []byte) error {\n\t// From json.Unmarshaler: By convention, to approximate the behavior of\n\t// Unmarshal itself, Unmarshalers implement UnmarshalJSON([]byte(\"null\")) as\n\t// a no-op.\n\tif string(b) == \"null\" {\n\t\treturn nil\n\t}\n\tif c == nil {\n\t\treturn fmt.Errorf(\"nil receiver passed to UnmarshalJSON\")\n\t}\n\n\tif ci, err := strconv.ParseUint(string(b), 10, 32); err == nil {\n\t\tif ci >= _maxCode {\n\t\t\treturn fmt.Errorf(\"invalid code: %d\", ci)\n\t\t}\n\n\t\t*c = Code(ci)\n\t\treturn nil\n\t}\n\n\tif jc, ok := strToCode[string(b)]; ok {\n\t\t*c = jc\n\t\treturn nil\n\t}\n\treturn fmt.Errorf(\"invalid code: %q\", string(b))\n}\n","sourceCodeStart":220,"sourceCodeEnd":251,"githubUrl":"https://github.com/grpc/grpc-go/blob/0c51461d27177d997e14c642fe18c11668fc09a3/codes/codes.go#L220-L251","documentation":"Returned by codes.Code.UnmarshalJSON when the JSON input is a numeric value that is >= _maxCode (17). gRPC status codes are only defined for 0 (OK) through 16 (Unauthenticated); any integer 17 or above is out of the valid range and cannot be mapped to a gRPC Code.","triggerScenarios":"Calling json.Unmarshal on a *codes.Code with input like 17, 99, or 500 — i.e. a numeric JSON token (no quotes) whose value is outside [0, 16]. Also triggered by serializing a custom/unknown code from another system and deserializing it as a number.","commonSituations":"Interoperability with a non-gRPC system that uses its own numeric error codes that exceed the gRPC range, or a protobuf/JSON payload whose 'code' field was populated with an HTTP-style status code (e.g. 404) instead of a gRPC code.","solutions":["Map the external numeric code into a valid gRPC Code (0–16) before unmarshaling, e.g. convert HTTP 404 to codes.NotFound(5).","If the JSON value is a string code name, send it as a quoted string (e.g. \"NOT_FOUND\") instead of a number.","Validate the numeric range [0,16] before assigning it to a codes.Code to surface the problem at the right boundary."],"exampleFix":"// before\nvar c codes.Code\njson.Unmarshal([]byte(`404`), &c) // invalid code: 404\n\n// after\nvar c codes.Code = codes.NotFound // map HTTP 404 -> gRPC NotFound before encoding","handlingStrategy":"validation","validationCode":"func parseNumericCode(b []byte) (codes.Code, error) {\n    n, err := strconv.ParseUint(string(b), 10, 32)\n    if err != nil {\n        return codes.OK, err\n    }\n    if n >= 17 {\n        return codes.OK, fmt.Errorf(\"code %d out of range [0,16]\", n)\n    }\n    return codes.Code(n), nil\n}","typeGuard":"func isValidNumericCode(n uint32) bool { return n < 17 }","tryCatchPattern":null,"preventionTips":["Map external (HTTP/vendor) numeric codes into [0,16] before producing JSON for codes.Code.","When interoperating, use string code names (quoted) that match the strToCode map exactly.","Document the valid range at the boundary where foreign codes enter your system."],"tags":["golang","json","grpc-codes","validation","interop"],"backgroundTag":null,"analyzedSha":"0c51461d27177d997e14c642fe18c11668fc09a3","analyzedAt":"2026-08-11T14:49:15.055Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}