◆Error Codes Wiki

gRPC Status UNAVAILABLE — Service Temporarily Unreachable or Overloaded

Error5xx server error

Overview

Fix gRPC UNAVAILABLE status code (14) when the service endpoint cannot be reached due to server overload, network issues, or service discovery failures.

Key Details

  • gRPC status code 14 (UNAVAILABLE) indicates the service is temporarily unable to handle the request
  • This is the gRPC equivalent of HTTP 503 Service Unavailable
  • UNAVAILABLE is a transient error that should be retried with exponential backoff
  • Common in microservice architectures when downstream services are deploying, scaling, or experiencing load
  • gRPC uses HTTP/2 as its transport protocol, so network issues affecting HTTP/2 can trigger this

Common Causes

  • Target gRPC service is down, restarting, or in the process of deploying
  • DNS resolution failed for the service endpoint in Kubernetes or service mesh
  • Load balancer or service mesh (Istio, Envoy) cannot route to a healthy backend
  • Connection pool exhausted due to high request volume without proper connection management

Steps

  1. 1Implement retry logic with exponential backoff and jitter for UNAVAILABLE errors
  2. 2Verify the service endpoint is correct and DNS resolves: nslookup service-name.namespace.svc.cluster.local
  3. 3Check service health in Kubernetes: kubectl get pods -l app=service-name and inspect readiness probes
  4. 4Review load balancer and service mesh configuration for proper health checks and circuit breaking
  5. 5Monitor connection pool metrics and increase max connections if the pool is exhausted

Tags

grpcunavailablemicroservicesstatus-14retry

More in 5xx Server Error

http-500-internal-server-errorHTTP 500 Internal Server Error — What It Means & How to Fix It
Critical
http-501-not-implementedHTTP 501 Not Implemented — What It Means & How to Fix It
Critical
http-502-bad-gatewayHTTP 502 Bad Gateway — What It Means & How to Fix It
Critical
http-503-service-unavailableHTTP 503 Service Unavailable — What It Means & How to Fix It
Critical
http-504-gateway-timeoutHTTP 504 Gateway Timeout — What It Means & How to Fix It
Critical
http-505-http-version-not-supportedHTTP 505 HTTP Version Not Supported — What It Means & How to Fix It
Critical

Frequently Asked Questions

Yes. UNAVAILABLE is explicitly meant to be retried. Use exponential backoff starting at 100ms with jitter. Most gRPC client libraries have built-in retry policies you can configure.