Catalog My learning Blog
gRPC and Protobuf Tutorial: Fast Microservice APIs · Phase 2 · Lesson 7 · 3 min read

gRPC Unary RPC Explained

On this page
  1. What is a unary RPC?
  2. What a unary call looks like on HTTP/2
  3. Calling a unary method with a deadline
  4. Unary call outcomes: OK, NotFound, DeadlineExceeded
  5. Rules for every unary call
  6. Check yourself

What is a unary RPC?

Most gRPC methods are unary: one request message in, one response message out. It's one of four call shapes, which the next days cover in turn:

Call typeClient sendsServer sendsEveryday picture
Unary (Day 7)One messageOne messageAsking a question and getting an answer
Server streaming (Day 8)One messageMany, over timeSubscribing to delivery updates
Client streaming (Day 9)Many, over timeOne messageUploading a pile of receipts, then getting one total
Bidirectional (Day 10)ManyMany, independentlyA phone call

Back to unary: GetOrder and CreateOrder in the course's service are unary:

Code
rpc GetOrder(GetOrderRequest) returns (GetOrderResponse);

What a unary call looks like on HTTP/2

  1. The client opens a new HTTP/2 stream on its existing connection and sends headers: :path /shop.v1.OrderService/GetOrder, content-type: application/grpc, a grpc-timeout if there's a deadline, plus any metadata (authorization).
  2. It sends the request as a length-prefixed protobuf message and half-closes its side.
  3. The server runs the handler, sends response headers, the response message, and trailers with grpc-status and grpc-message.

The status travels in trailers, after the body. That's why even an error is an HTTP 200 at the HTTP level: the gRPC status is what matters.

A unary call opens one HTTP/2 stream: headers and metadata, a single request message, then a response message followed by trailers carrying the gRPC status.
A unary call opens one HTTP/2 stream: headers and metadata, a single request message, then a response message followed by trailers carrying the gRPC status.

Calling a unary method with a deadline

Every call takes a context, which carries the deadline, cancellation and metadata:

Code
ctx, cancel := context.WithTimeout(context.Background(), 500*time.Millisecond)
defer cancel()
ctx = metadata.AppendToOutgoingContext(ctx, "authorization", "Bearer demo-token")

resp, err := client.GetOrder(ctx, &shopv1.GetOrderRequest{OrderId: "ord_42"})
if err != nil {
	switch status.Code(err) {
	case codes.NotFound:
		// show "no such order"
	case codes.DeadlineExceeded, codes.Unavailable:
		// maybe retry, if the method is safe to retry (Day 22)
	default:
		return err
	}
}

The Go call blocks until the response or an error. Other languages offer both styles: Python stubs have blocking methods and .future() variants (or the grpc.aio async API), Java has blocking, future and async stubs, and C# returns awaitable calls.

Unary call outcomes: OK, NotFound, DeadlineExceeded

Calls to the course's GetOrder, as reported by grpcurl and the Go client:

Code
no token        -> Unauthenticated: missing or invalid bearer token
ord_42          -> OK, order returned
ord_9           -> NotFound: order "ord_9" not found
empty order_id  -> InvalidArgument: order_id is required (with BadRequest details)
"slow" order,
500 ms deadline -> DeadlineExceeded after 500ms

And the server's interceptor log for the same calls:

Code
unary /shop.v1.OrderService/GetOrder code=OK took=0s
unary /shop.v1.OrderService/GetOrder code=NotFound took=0s
unary /shop.v1.OrderService/GetOrder code=InvalidArgument took=0s
unary /shop.v1.OrderService/GetOrder code=Canceled took=500ms

Each outcome has a distinct, standard code (Day 14) the client can act on.

Rules for every unary call

  • Always set a deadline (Day 15). A call without one can hang forever if the server stalls.
  • Reuse the connection and client across calls.
  • Check the status code, not just whether err is nil, and decide retry behavior by code and method (Day 22).
  • Keep messages reasonably small: the default maximum received message size is 4 MB in most implementations. For large data, stream it (Day 9) or use object storage.
  • Use unary unless you need streaming: it's simpler to load balance, retry, cache and observe.

Check yourself

The gRPC status is sent in HTTP/2 trailers after the response body. HTTP 200 only means the stream itself worked; the real outcome is in the grpc-status trailer, which is why HTTP-level monitoring alone misses gRPC errors.

Without one, a stalled server or network can leave the call waiting forever, holding goroutines, connections and memory on both sides. Under load, those stuck calls pile up until the client itself fails.

Metadata, sent as HTTP/2 headers alongside the request, usually as authorization: Bearer <token>. Interceptors on the server read it before the handler runs.

Client streaming: the client sends many messages over one stream and the server replies once at the end with a summary. It avoids the per-call overhead of thousands of unary calls and lets the server process points as they arrive.