HTTP 500 вместо ожидаемого 404 не всегда создаёт backend. Сначала посмотрите, дошёл ли запрос до RPC method и какой gRPC status вышел из сервиса. gRPC-Gateway отдельно обрабатывает ошибку unary RPC, ошибку HTTP routing до вызова сервиса и сбой server stream после начала ответа. У этих веток разные hooks, поэтому одна универсальная замена кода часто исправляет тест и ломает другой сценарий.

Не используйте таблицу HTTP-to-gRPC из gRPC Core в обратную сторону. Официальная документация прямо указывает: она нужна клиенту, когда intermediary вернул HTTP response без grpc-status; mapping несимметричен и не предназначен серверу для выбора HTTP status. Для gateway зафиксируйте собственный внешний контракт и опирайтесь на status.Code(err), а не на текст сообщения.

Один внешний код может возникнуть в трёх местах

НаблюдениеИсточникСледующий шаг
Backend log содержит NOT_FOUNDUnary RPC error mappingПроверить WithErrorHandler и default mapping
Backend вообще не видел запросGateway routingПроверить path, method и WithRoutingErrorHandler
HTTP уже 200, ошибка в последнем chunkServer streamПроверить WithStreamErrorHandler и schema envelope
Status меняется после proxyIngress или CDNСнять response до и после intermediary

Добавьте в один diagnostic event: route template, HTTP method, RPC full method, grpc code, выбранный handler, final HTTP status и request ID. Не записывайте authorization metadata и полный error details. По этой строке видно, где расходятся ожидание и факт, без угадывания по сообщению REST-клиента.

Backend возвращает смысл, gateway переводит транспорт

func publicError(ctx context.Context, mux *runtime.ServeMux,
  m runtime.Marshaler, w http.ResponseWriter, r *http.Request, err error) {
    st := status.Convert(err)
    logCode(ctx, st.Code())
    runtime.DefaultHTTPErrorHandler(ctx, mux, m, w, r, safeStatus(st))
}

mux := runtime.NewServeMux(
    runtime.WithErrorHandler(publicError),
    runtime.WithRoutingErrorHandler(publicRoutingError),
    runtime.WithStreamErrorHandler(publicStreamError),
)

Пример условный: safeStatus сохраняет code, но удаляет внутренние details и заменяет небезопасное message. Domain validation должна вернуть INVALID_ARGUMENT, отсутствие объекта — NOT_FOUND, отсутствие credentials — UNAUTHENTICATED, а запрет на объект — PERMISSION_DENIED. UNKNOWN и INTERNAL не превращают в текст database error. Маппинг централизуется, чтобы каждый handler не создавал собственную семантику.

Routing error не является ответом RPC

Если клиент вызвал правильный path неправильным HTTP method, gRPC-Gateway может обработать это до backend. Документация показывает отдельный WithRoutingErrorHandler: по умолчанию routing statuses переводятся в gRPC errors, после чего могут снова стать другим HTTP code. Например, чтобы сохранить 405 Method Not Allowed, используют HTTPStatusError в routing handler. Такой override должен относиться только к routing branch.

Не выставляйте status после записи body: в HTTP headers уже могли уйти. Для успешного Create с 201 gateway допускает forward response option и metadata, но custom metadata нельзя слепо принимать от внешнего клиента. Удаляйте технический x-http-code из публичного ответа и разрешайте ограниченный набор статусов, сформированный доверенным backend.

Retry зависит от grpc code, а не от красоты HTTP

  • INVALID_ARGUMENT и FAILED_PRECONDITION не становятся автоматическим retry только из-за HTTP 400.
  • UNAVAILABLE обычно временный, но повтор неидемпотентной операции всё равно требует idempotency key.
  • DEADLINE_EXCEEDED не доказывает, что операция не завершилась на сервере.
  • UNAUTHENTICATED предлагает обновить credential; PERMISSION_DENIED — не тот же сценарий.
  • UNKNOWN требует диагностики источника, а не безграничных повторов клиентом.

REST SDK может принимать решение по HTTP status, поэтому документируйте mapping как часть API version. Если изменить NOT_FOUND с 404 на 200 с полем error, кеши, observability и retry middleware перестанут видеть ошибку одинаково. Временно поддерживать два формата можно только с явной версией и метрикой старых клиентов.

Контрактный тест проходит через настоящий gateway

case                         grpc status          expected HTTP
missing resource             NOT_FOUND            404
invalid field                INVALID_ARGUMENT      400
missing bearer token         UNAUTHENTICATED       401
wrong HTTP method            no RPC call           405
backend unavailable          UNAVAILABLE           documented 5xx
stream fails after chunk     stream envelope       HTTP already started

Для каждой пары проверяйте status, Content-Type, безопасную форму JSON, error code и отсутствие stack trace. Отдельный тест вызывает backend напрямую и подтверждает исходный grpc status; второй проходит через gateway; третий — через ingress. Так изменение можно привязать к конкретной границе, а не маскировать proxy rewrite новой настройкой сервиса.

Что приложить к разбору

Нужны версии grpc-gateway и protobuf, конфигурация ServeMux, один sanitized grpc status с details, фактический HTTP response до ingress и после него, а также OpenAPI contract. Результат считается исправленным, когда один gRPC code стабильно даёт документированный публичный status, routing не вызывает backend, stream error сохраняет корректный envelope, а клиенты не повторяют опасные операции автоматически.

Проверенные источники