English for gRPC Error Handling

gRPC is a high-performance remote procedure call framework widely used in microservices architectures. Unlike REST, which uses HTTP status codes for error communication, gRPC has its own set of status codes and error model. If you work with gRPC services and collaborate in English, knowing how to discuss error handling clearly will make your code reviews, design discussions, and documentation much more effective.

Key Vocabulary

Status code gRPC defines a set of standard status codes that indicate the outcome of an RPC call. Unlike HTTP status codes, gRPC status codes are language-agnostic and semantically specific. Common examples include OK, NOT_FOUND, INVALID_ARGUMENT, and UNAVAILABLE. Example: “When the requested resource doesn’t exist, we return a NOT_FOUND status rather than a generic error.”

Trailing metadata In gRPC, additional error information can be attached to a response as trailing metadata — key-value pairs sent after the response body. This allows servers to provide structured error details alongside the status code. Example: “We include the field validation errors in the trailing metadata so the client can display specific error messages to the user.”

Deadline A deadline is a point in time by which an RPC must complete. If the deadline is exceeded, the call fails with a DEADLINE_EXCEEDED status. Setting appropriate deadlines is a key part of building resilient gRPC services. Example: “We set a two-second deadline on all calls to the inventory service to prevent cascading timeouts.”

Retry policy A retry policy defines the conditions under which a failed RPC should be automatically retried, and how many times. gRPC supports configurable retry policies at the channel level. Example: “We have a retry policy configured to retry up to three times on UNAVAILABLE errors with exponential backoff.”

Interceptor An interceptor is middleware for gRPC — a component that intercepts outgoing or incoming calls to add cross-cutting concerns such as logging, authentication, or error enrichment. Example: “Our server-side interceptor catches all unhandled exceptions and maps them to appropriate gRPC status codes.”

Common Scenarios Where This Language Is Used

In a code review: “I notice this handler returns INTERNAL for all errors. We should be more specific — if the input is invalid, we should return INVALID_ARGUMENT so the client knows it’s a request problem rather than a server failure.”

In an API design discussion: “For this RPC, what status code should we return when the user tries to create a resource that already exists? In gRPC, ALREADY_EXISTS is the conventional choice for this scenario.”

When debugging an incident: “The alert shows a spike in DEADLINE_EXCEEDED errors on the payment service. This usually means either the downstream database is slow or a client is setting an unreasonably short deadline. Let’s check both.”

When writing service documentation: Documenting which status codes a gRPC method can return is essential for consumer teams. Each possible error condition should be listed with the status code, a description, and the recommended client-side response.

Useful Phrases for gRPC Error Handling Discussions

• “This RPC can return NOT_FOUND if the user doesn’t exist, or PERMISSION_DENIED if the caller lacks access.”
• “We should always set a deadline on outgoing RPCs to avoid indefinite blocking.”
• “The UNAVAILABLE status is typically retriable — the client should back off and try again.”
• “We’re using an interceptor to map domain exceptions to appropriate gRPC status codes.”
• “The error details extension lets us include structured error information alongside the status code.”
• “A FAILED_PRECONDITION is appropriate here — the operation is not allowed given the current state of the resource.”
• “We should differentiate between INVALID_ARGUMENT for bad inputs and OUT_OF_RANGE for values outside acceptable bounds.”
• “The client should treat INTERNAL errors as non-retriable — something unexpected happened on the server.”
• “We propagate the deadline from the incoming request to all outgoing RPCs to respect the caller’s timeout budget.”
• “Let’s add a test that verifies the correct status code is returned for each error scenario.”

Documenting gRPC Error Responses

When documenting a gRPC service, each method definition should include an error table. For each possible error, document: the status code, the condition that triggers it, and what the client should do.

Example documentation for a GetUser method:

• OK: The user was found and returned successfully.
• NOT_FOUND: No user exists with the specified ID. The client should display a “user not found” message.
• INVALID_ARGUMENT: The provided user ID is not a valid UUID. The client should validate input before calling this method.
• PERMISSION_DENIED: The caller does not have permission to access this user’s data. The client should redirect to the login page if the user’s session has expired.
• INTERNAL: An unexpected server error occurred. The client should display a generic error message and log the error for investigation.

Practice Suggestion

Review the documentation for a gRPC service you work with or are familiar with. Identify one method that lacks clear error documentation. Write a complete error table for that method in English, covering all the status codes that method could plausibly return and what the client should do in each case. Focus on being precise about the conditions that trigger each error and the recommended client behaviour.