2
gRPC
2 UNKNOWN
An unknown error occurred. This may be returned when a server raises an exception that doesn't map to any known gRPC status code.
On this page
When You See This Code
The server threw an unhandled exception or returned an error that gRPC couldn't classify into a more specific status code.
How to Fix
Check the server logs for the underlying exception. Wrap server-side errors with explicit gRPC status codes instead of letting them bubble up as UNKNOWN.
Specification
Compare With
Guides
HTTP Trailers: Sending Metadata After the Body
HTTP Fundamentals
Choosing the Right HTTP Status Codes for REST APIs
API Design & Best Practices
gRPC Status Codes: A Practical Guide
API Design & Best Practices
How to Implement and Handle Rate Limiting (429)
API Design & Best Practices
API Versioning Strategies: URL, Header, and Query Param
API Design & Best Practices
Designing Consistent API Error Responses
API Design & Best Practices
Debugging Timeout Errors: 408 and 504
Debugging & Troubleshooting
Debugging gRPC Errors and Status Codes
Debugging & Troubleshooting
API Keys vs OAuth vs JWT: Choosing the Right Auth Method
Security & Authentication
Implementing Mutual TLS (mTLS) for API Security
Security & Authentication
gRPC Streaming Patterns Guide
Real-Time Protocols
gRPC Streaming vs REST Polling: Real-Time Data Delivery
Real-Time Protocols
Implementing Retry with Exponential Backoff
Error Handling Patterns
Circuit Breaker Pattern for API Resilience
Error Handling Patterns
Timeout Budget Patterns for Microservices
Error Handling Patterns
Bulkhead Pattern: Isolating Failures in Distributed Systems
Error Handling Patterns
Saga Pattern: Managing Distributed Transactions with Compensating Actions
Error Handling Patterns
Error Budgets and SLOs: When to Accept Errors
Error Handling Patterns
Fallback Strategies: Default Values, Cached Responses, and Degraded Modes
Error Handling Patterns
gRPC Error Handling Best Practices
Framework Cookbooks
Rust Actix-web Error Handling: ResponseError Trait and Custom Errors
Framework Cookbooks
Taming Tail Latency: Why P99 Matters More Than Average
Performance & Optimization
RFC 9114: HTTP/3 Protocol Deep Dive
Protocol Deep Dives
RFC 7231/9110: HTTP Method Semantics — Safe, Idempotent, and Cacheable
Protocol Deep Dives
Migrating from REST to gRPC
Migration & Upgrades
Migrating from SOAP to REST APIs
Migration & Upgrades
API Migration: Monolith to Microservices
Migration & Upgrades
Reverse Proxy Configuration: Nginx, Caddy, and HAProxy
Production Infrastructure
Load Balancer Health Checks: HTTP, TCP, and gRPC Probes
Production Infrastructure
Connection Draining: Graceful Shutdown Without Dropping Requests
Production Infrastructure
Observability for HTTP Status Codes: Metrics, Logs, and Alerts
Production Infrastructure
Request ID and Distributed Tracing: Correlating Logs Across Services
Production Infrastructure
API Gateway Patterns: Architecture and Use Cases
API Gateway Patterns
Circuit Breaker Pattern at the API Gateway
API Gateway Patterns
API Gateway Request Routing: Path, Header, and Content-Based
API Gateway Patterns
Request and Response Transformation at the API Gateway
API Gateway Patterns
API Gateway Retry and Timeout Policies
API Gateway Patterns
API Gateway Logging and Analytics
API Gateway Patterns
API Versioning Through the Gateway: URI, Header, and Media Type
API Gateway Patterns
API Testing Strategies: Unit, Integration, Contract, and E2E
Testing & Mocking
Mock Servers for API Development: WireMock, Prism, and Custom Mocks
Testing & Mocking
Contract Testing with Pact: Consumer-Driven API Contracts
Testing & Mocking
Load Testing APIs: k6, Locust, and Artillery
Testing & Mocking
Chaos Engineering for APIs: Injecting Faults and Status Codes
Testing & Mocking
API Performance Benchmarking: Establishing and Tracking Baselines
Testing & Mocking
Debugging Scenarios
Specifications
Glossary
Rate Limiting
API Gateway
SDK (Software Development Kit)
Bulk Operations
Mutual TLS (mTLS)
Latency
Timeout
Load Balancer
Connection Pooling
Bandwidth
Retry Strategy
Circuit Breaker
Error Boundary
Timeout Budget
Backpressure
Exponential Backoff
Jitter
Thundering Herd
Bulkhead Pattern
Error Code Mapping
Error Rate
Poison Message
Fail Open / Fail Closed
Request-Response Model
Multiplexing
Backward Compatibility
Protocol Buffers (Protobuf)
Serialization
Protocol Negotiation
Message Framing
Wire Format
Extension Mechanism
Full-Duplex
ALPN (Application-Layer Protocol Negotiation)
Text vs Binary Protocol
SRV Record
gRPC Streaming
gRPC Metadata
gRPC-Web
Service Mesh
Sidecar Proxy
Service Discovery
Distributed Tracing
Observability
Correlation ID
Rate Limiter Algorithm
Container Orchestration
Readiness Probe
SLA / SLO / SLI
gRPC Channel
gRPC Interceptor
gRPC Deadline
gRPC Status Code
gRPC Service Definition
Unary RPC
Server Streaming RPC
Client Streaming RPC
Bidirectional Streaming RPC
Protobuf Message
gRPC Reflection
gRPC Health Checking Protocol
gRPC Load Balancing
gRPC Retry Policy
gRPC Error Details
gRPC-Gateway
gRPC Keepalive
RPC (Remote Procedure Call)
Protobuf Oneof
gRPC Compression
TLS 1.3
Layer 4 Load Balancing
Layer 7 Load Balancing
Consistent Hashing
Weighted Round Robin
Least Connections
HAProxy
Envoy Proxy
Backend Pool
Request Routing
Connection Multiplexing (Proxy)
xDS (Discovery Service Protocol)
Frequently Asked Questions
What is gRPC 2 UNKNOWN?
An unknown error occurred. This may be returned when a server raises an exception that doesn't map to any known gRPC status code.
When do you see gRPC 2 UNKNOWN?
The server threw an unhandled exception or returned an error that gRPC couldn't classify into a more specific status code.
How to fix gRPC 2 UNKNOWN?
Check the server logs for the underlying exception. Wrap server-side errors with explicit gRPC status codes instead of letting them bubble up as UNKNOWN.