---
title: "Answer with the standard gRPC status codes · Agent Wranglers"
url: https://agentwranglers.se/playbook/api-design/graphql-and-grpc/grpc-status-codes
id: API-90
level: Recommended
updated: 2026-10-22
tokens: 809
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Answer with the standard gRPC status codes

For AI agents: the [site map](https://agentwranglers.se/llms.txt) lists everything here, and this page sits under [GraphQL and gRPC](https://agentwranglers.se/playbook/api-design/graphql-and-grpc.md).

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers.md). Updated 2026-10-22.

- ID: API-90
- Level: Recommended
- Chapter: [GraphQL and gRPC](https://agentwranglers.se/playbook/api-design/graphql-and-grpc.md)
- Rule: Return one of the 17 standard gRPC status codes with the meaning grpc.io gives it. Never return `OK` with an error inside the message, and never invent new numeric codes.
- Check: A test triggers each failure of each method and compares the code with a table in the service docs. No answer carries `OK` with an error field set. Every code is one of the 17 listed on grpc.io.
- How: Clients, proxies and retry policies act on the code. `UNAVAILABLE` means the client may retry the same call, `ABORTED` means retry at a higher level, and `FAILED_PRECONDITION` means do not retry until something changes. `PERMISSION_DENIED` means the caller is known but not allowed, and `UNAUTHENTICATED` means no valid credentials. Put field details in the standard rich error model, as [name every field that failed](https://agentwranglers.se/playbook/api-design/errors/validation-errors.md) does for REST.

## Examples

**Using these examples:** they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

### Go example

```go
func (s *server) GetInvoice(ctx context.Context, req *pb.GetInvoiceRequest) (*pb.Invoice, error) {
	invoice, err := s.store.Find(ctx, req.GetId())
	if errors.Is(err, store.ErrNotFound) {
		return nil, status.Errorf(codes.NotFound, "invoice %s not found", req.GetId())
	}
	if err != nil {
		return nil, status.Error(codes.Unavailable, "invoice store unavailable")
	}
	return invoice, nil
}
```

### Python example

```python
class InvoiceService(invoices_pb2_grpc.InvoiceServiceServicer):
    def GetInvoice(self, request, context):
        invoice = store.find(request.id)
        if invoice is None:
            context.abort(grpc.StatusCode.NOT_FOUND, f"invoice {request.id} not found")
        return invoice
```

## Sources

- [gRPC, Status codes](https://grpc.io/docs/guides/status-codes/)
- [gRPC, Error handling](https://grpc.io/docs/guides/error/)

## Related rules

- API-18 [Name every field that failed](https://agentwranglers.se/playbook/api-design/errors/validation-errors.md) in API design

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), which requires credit with a link. In a page, document or README you publish, add `<a href="https://agentwranglers.se/playbook/api-design/graphql-and-grpc/grpc-status-codes">Agent Wranglers API design playbook</a>`. In code you write, add a comment next to it with the same link.

- Previous: [Set a deadline on every gRPC call and pass it on](https://agentwranglers.se/playbook/api-design/graphql-and-grpc/grpc-deadlines.md)
- [GraphQL and gRPC](https://agentwranglers.se/playbook/api-design/graphql-and-grpc.md)