What are gRPC status codes, how do they map to HTTP codes, and how do you return rich error details?

package com.bank.grpc;

import io.grpc.Status;
import io.grpc.stub.StreamObserver;

public class AccountGrpcService
        extends AccountServiceGrpc.AccountServiceImplBase {

    @Override
    public void getBalance(
            BalanceRequest request,
            StreamObserver<BalanceResponse> observer) {

        String accountId = request.getAccountId();
        if (accountId == null || accountId.isBlank()) {
            observer.onError(
                Status.INVALID_ARGUMENT
                    .withDescription("Account ID must not be empty")
                    .asRuntimeException()
            );
            return;
        }

        Account account = findAccount(accountId);
        if (account == null) {
            observer.onError(
                Status.NOT_FOUND
                    .withDescription("Account " + accountId
                        + " not found")
                    .asRuntimeException()
            );
            return;
        }

        observer.onNext(BalanceResponse.newBuilder()
                .setBalance(account.getBalance().toPlainString())
                .build());
        observer.onCompleted();
    }
}

package com.bank.grpc;

import io.grpc.Status;
import io.grpc.StatusRuntimeException;
import java.math.BigDecimal;

public class TransferClient {

    public BigDecimal transferWithRetry(
            String from, String to, String amount) {
        int maxRetries = 3;
        for (int i = 0; i < maxRetries; i++) {
            try {
                return doTransfer(from, to, amount);
            } catch (StatusRuntimeException e) {
                Status.Code code = e.getStatus().getCode();
                if (code == Status.Code.UNAVAILABLE) {
                    System.out.println("Retry " + (i + 1)
                        + ": service unavailable");
                    continue; // Safe to retry
                }
                if (code == Status.Code.INVALID_ARGUMENT) {
                    throw e; // Do NOT retry
                }
                throw e; // Unknown, do not retry
            }
        }
        throw new RuntimeException("Transfer failed after retries");
    }

    private BigDecimal doTransfer(
            String from, String to, String amount) {
        // Stub call
        return new BigDecimal("50000.00");
    }
}

package com.bank.grpc;

import com.google.protobuf.Any;
import com.google.rpc.BadRequest;
import com.google.rpc.ErrorInfo;
import io.grpc.protobuf.StatusProto;
import io.grpc.stub.StreamObserver;
import java.math.BigDecimal;

public class TransferGrpcService
        extends TransferServiceGrpc.TransferServiceImplBase {

    @Override
    public void transfer(
            TransferRequest request,
            StreamObserver<TransferResponse> observer) {

        BigDecimal amount = new BigDecimal(request.getAmount());

        if (amount.compareTo(BigDecimal.ZERO) <= 0) {
            // Rich error with BadRequest field violation
            BadRequest badRequest = BadRequest.newBuilder()
                .addFieldViolations(
                    BadRequest.FieldViolation.newBuilder()
                        .setField("amount")
                        .setDescription(
                            "Amount must be positive, got: "
                            + amount.toPlainString())
                        .build()
                ).build();

            com.google.rpc.Status status =
                com.google.rpc.Status.newBuilder()
                    .setCode(com.google.rpc.Code.INVALID_ARGUMENT_VALUE)
                    .setMessage("Invalid transfer request")
                    .addDetails(Any.pack(badRequest))
                    .build();

            observer.onError(
                StatusProto.toStatusRuntimeException(status));
            return;
        }

        // Process transfer...
        observer.onNext(TransferResponse.newBuilder()
                .setSuccess(true).build());
        observer.onCompleted();
    }
}

package com.bank.client;

import com.google.rpc.BadRequest;
import io.grpc.StatusRuntimeException;
import io.grpc.protobuf.StatusProto;

public class TransferErrorHandler {

    public void handleError(StatusRuntimeException e) {
        com.google.rpc.Status status =
            StatusProto.fromThrowable(e);

        if (status != null) {
            System.out.println("Code: " + status.getCode());
            System.out.println("Message: " + status.getMessage());

            for (com.google.protobuf.Any detail
                    : status.getDetailsList()) {
                if (detail.is(BadRequest.class)) {
                    try {
                        BadRequest br = detail.unpack(
                            BadRequest.class);
                        for (BadRequest.FieldViolation fv
                                : br.getFieldViolationsList()) {
                            System.out.println("Field: "
                                + fv.getField()
                                + " – " + fv.getDescription());
                        }
                    } catch (Exception ex) {
                        ex.printStackTrace();
                    }
                }
            }
        }
    }
}

Code: 3
Message: Invalid transfer request
Field: amount – Amount must be positive, got: -500.00

// WRONG: INTERNAL for a client error
observer.onError(
    Status.INTERNAL
        .withDescription("Account not found")
        .asRuntimeException());
// Should be NOT_FOUND, not INTERNAL

// WRONG: leaking internal details
observer.onError(
    Status.INTERNAL
        .withDescription("SQL error: ORA-12154 on db-prod-03")
        .asRuntimeException());
// The client can read this!

// CORRECT: appropriate code, safe description
observer.onError(
    Status.NOT_FOUND
        .withDescription("Account SAV2001 not found")
        .asRuntimeException());