{"record":{"id":"ef868885c6805a85","repo":"temporalio/temporal","slug":"unexpected-response-status-q","errorCode":null,"errorMessage":"unexpected response status: %q","messagePattern":"unexpected response status: %q","errorType":"http","errorClass":null,"httpStatus":null,"severity":"error","filePath":"common/nexus/nexusrpc/client.go","lineNumber":450,"sourceCode":"\t\treturn nexus.HandlerErrorTypeConflict, nil\n\tcase http.StatusUnauthorized:\n\t\treturn nexus.HandlerErrorTypeUnauthenticated, nil\n\tcase http.StatusForbidden:\n\t\treturn nexus.HandlerErrorTypeUnauthorized, nil\n\tcase http.StatusNotFound:\n\t\treturn nexus.HandlerErrorTypeNotFound, nil\n\tcase http.StatusTooManyRequests:\n\t\treturn nexus.HandlerErrorTypeResourceExhausted, nil\n\tcase http.StatusInternalServerError:\n\t\treturn nexus.HandlerErrorTypeInternal, nil\n\tcase http.StatusNotImplemented:\n\t\treturn nexus.HandlerErrorTypeNotImplemented, nil\n\tcase http.StatusServiceUnavailable:\n\t\treturn nexus.HandlerErrorTypeUnavailable, nil\n\tcase nexus.StatusUpstreamTimeout:\n\t\treturn nexus.HandlerErrorTypeUpstreamTimeout, nil\n\tdefault:\n\t\treturn \"\", fmt.Errorf(\"unexpected response status: %q\", response.Status)\n\t}\n}\n\nfunc retryBehaviorFromHeader(header http.Header) nexus.HandlerErrorRetryBehavior {\n\tswitch strings.ToLower(header.Get(headerRetryable)) {\n\tcase \"true\":\n\t\treturn nexus.HandlerErrorRetryBehaviorRetryable\n\tcase \"false\":\n\t\treturn nexus.HandlerErrorRetryBehaviorNonRetryable\n\tdefault:\n\t\treturn nexus.HandlerErrorRetryBehaviorUnspecified\n\t}\n}\n\nfunc getUnsuccessfulStateFromHeader(response *http.Response, body []byte) (nexus.OperationState, error) {\n\tstate := nexus.OperationState(response.Header.Get(headerOperationState))\n\tswitch state {\n\tcase nexus.OperationStateCanceled, nexus.OperationStateFailed:","sourceCodeStart":432,"sourceCodeEnd":468,"githubUrl":"https://github.com/temporalio/temporal/blob/bde624efd13fbd3843654058db6d9c716166318b/common/nexus/nexusrpc/client.go#L432-L468","documentation":"httpStatusCodeToHandlerErrorType maps HTTP response statuses from a Nexus handler endpoint onto nexus.HandlerErrorType values. When the server returns a status code that has no mapping (not 4xx/5xx cases like 501, 503, or the upstream-timeout status), it returns this error because the SDK cannot classify the failure. It signals an unanticipated response from the peer, not a domain error.","triggerScenarios":"Calling a Nexus operation via the nexusrpc client when the HTTP handler (or an intermediary proxy/gateway) returns an unmapped status code, e.g. 400, 401, 404, 500, 502, or a nonstandard status, inside defaultErrorFromResponse.","commonSituations":"A reverse proxy or API gateway intercepting the request and returning 401/404/502; a misconfigured Nexus endpoint URL; a server-side bug returning 500 instead of a Nexus failure; a newer server returning statuses the older client SDK does not know.","solutions":["Inspect the wrapped status in the error message and check server/proxy logs to find why that status was returned.","Verify the Nexus endpoint URL, routing, and authentication so requests reach the actual handler instead of a proxy error page.","Fix the server to return proper nexus.HandlerError failures (e.g. Unavailable, NotSupported) instead of raw HTTP errors like 500.","If the status is a valid new Nexus status, upgrade the client SDK to a version that maps it."],"exampleFix":"// before\nif resp.StatusCode == http.StatusInternalServerError { /* client has no mapping -> error */ }\n// after\n// server side: return a proper handler failure instead of a bare 500\nreturn nil, nexus.HandlerErrorf(nexus.HandlerErrorTypeInternal, \"operation failed: %v\", cause)","handlingStrategy":"try-catch","validationCode":"// Peek at endpoint health before calling operations\nresp, err := http.Get(endpointURL)\nif err == nil && (resp.StatusCode < 200 || resp.StatusCode > 299) && resp.StatusCode != http.StatusServiceUnavailable {\n    log.Printf(\"endpoint returned unmapped status %d; check proxy/auth\", resp.StatusCode)\n}","typeGuard":null,"tryCatchPattern":"result, err := client.ExecuteOperation(ctx, svc, op, input)\nvar statusErr *errors.StatusError // or inspect wrapped error string\nif err != nil {\n    if strings.Contains(err.Error(), \"unexpected response status\") {\n        // unclassified peer/proxy failure: log raw status, decide retry vs abort\n        return fmt.Errorf(\"nexus endpoint misbehaving: %w\", err)\n    }\n    return err\n}","preventionTips":["Ensure the Nexus endpoint URL points directly at the handler service, not an auth-gated proxy","Keep client and server nexusrpc SDK versions in sync","Monitor for gateway-generated statuses (401/404/502) in endpoint metrics","Make servers return nexus.HandlerError failures rather than raw HTTP errors"],"tags":["nexus","http","status-code","error-mapping"],"backgroundTag":"unexpected-http-status","analyzedSha":"bde624efd13fbd3843654058db6d9c716166318b","analyzedAt":"2026-09-01T07:18:39.080Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}