How to Map Errors Across Protocols

Different protocols use different error codes for the same logical conditions. This decision tree helps you find the equivalent error code when integrating HTTP APIs with gRPC backends, WebSocket connections, DNS lookups, or SMTP delivery — keeping your error semantics consistent across layers.

Decision Steps

Are you starting from an HTTP error and need to find the equivalent in another protocol?

Is the HTTP error a 401 or 403 (authentication/authorization)?

Is it a 401 (no credentials / invalid credentials)?

Is the HTTP error a 404 (not found)?

Is the HTTP error a 5xx (server error: 500, 503, 504)?

Is it a 503 or 504 (service unavailable or timeout)?

Are you starting from a gRPC error and need the HTTP equivalent?

Is the gRPC error UNAUTHENTICATED (16) or PERMISSION_DENIED (7)?

Possible Outcomes

401-unauthorized HTTP 401 ↔ gRPC UNAUTHENTICATED

403-forbidden HTTP 403 ↔ gRPC PERMISSION_DENIED

404-not-found HTTP 404 ↔ gRPC NOT_FOUND ↔ DNS NXDOMAIN

500-internal-server-error HTTP 500 ↔ gRPC INTERNAL ↔ WS 1011

503-service-unavailable HTTP 503 ↔ gRPC UNAVAILABLE ↔ WS 1001

Related Status Codes

HTTP 401 HTTP 403 HTTP 404 HTTP 500 HTTP 503 gRPC 5 gRPC 7 gRPC 13 gRPC 14 gRPC 16 DNS 3 WebSocket 1008

Related Terms

Status Code REST (Representational State Transfer) Authentication gRPC Streaming HTTP Semantics (RFC 9110)