Modelos avançados de erros com google.rpc.Status
Vá além dos códigos de status simples anexando detalhes de erro estruturados e legíveis por máquina com o modelo google.rpc.Status e os tipos padrão de detalhes de erro.
Modelos avançados de erros com google.rpc.Status é uma aula grátis de gRPC & High Performance APIs no CoddyKit. Esta é a aula 4 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de gRPC & High Performance APIs, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de gRPC & High Performance APIs inclui 4 aulas no total.
Partes desta aula ainda não foram traduzidas e aparecem em inglês.
Limits of Plain Status Codes
A bare status code plus a message tells the client that something failed, but not the structured why. Clients often need field-level validation errors, retry hints, or quota info.
The rich error model attaches structured details to a status.
The google.rpc.Status Message
The core type is google.rpc.Status with three fields:
- code: a numeric status code
- message: developer-facing text
- details: a repeated list of
Anypayloads
Standard Detail Types
Google defines reusable detail messages in google/rpc/error_details.proto:
BadRequest— field violationsRetryInfo— when to retryQuotaFailure— limit exceededErrorInfo— machine-readable reason
BadRequest for Validation
BadRequest carries a list of FieldViolation entries, each naming a bad field and describing the problem. Perfect for form validation responses.
Building a Rich Error in Go
The status package lets you create a status and append typed details with WithDetails.
st := status.New(codes.InvalidArgument, 'invalid request')
v := &errdetails.BadRequest_FieldViolation{
Field: 'email', Description: 'must be a valid address',
}
br := &errdetails.BadRequest{FieldViolations: []*errdetails.BadRequest_FieldViolation{v}}
st, _ = st.WithDetails(br)
return st.Err()RetryInfo for Backoff Hints
For temporary failures, attach RetryInfo with a retry_delay. A well-behaved client reads this and waits before retrying.
ri := &errdetails.RetryInfo{RetryDelay: durationpb.New(2 * time.Second)}
st, _ = status.New(codes.Unavailable, 'busy').WithDetails(ri)ErrorInfo for Stable Reasons
ErrorInfo gives a stable reason string and a domain plus metadata. Unlike free-text messages, clients can branch on these reliably.
ei := &errdetails.ErrorInfo{
Reason: 'EMAIL_TAKEN', Domain: 'auth.example.com',
}Reading Details on the Client
The client converts the returned error back to a status and inspects each detail with a type switch.
st := status.Convert(err)
for _, d := range st.Details() {
switch t := d.(type) {
case *errdetails.BadRequest:
handleFieldErrors(t)
case *errdetails.RetryInfo:
waitThenRetry(t.RetryDelay)
}
}How Details Travel
Details are serialized into the grpc-status-details-bin trailer as a binary Status proto. Languages with the rich-error libraries decode it automatically.
Best Practices
Use the rich model wisely:
- Prefer standard detail types for interoperability
- Never leak secrets in messages or details
- Keep
ErrorInfo.reasonvalues stable and documented - Pair
RetryInfowith truly retryable codes
Cross-Language Interop
Because the model is defined in protobuf, a Go server can emit a BadRequest that a Java or Python client decodes identically. This consistency is the whole point of the standard types.
Quick Check
Test your rich error knowledge.
Recap
You learned the rich error model:
google.rpc.Statuscarries code, message, and repeated detailAnypayloads- Standard types:
BadRequest,RetryInfo,QuotaFailure,ErrorInfo - Build with
WithDetails, read with a type switch overDetails() - Details travel in the
grpc-status-details-bintrailer - Standard types give cross-language consistency
Aprenda gRPC & High Performance APIs com um tutor de IA — grátis
Escreva e execute código real no seu navegador, obtenha ajuda instantânea de um tutor de IA 24/7 e continue de onde parou na web ou no app.
- Cursos
- 12
- Aulas
- 48
Perguntas Frequentes
A aula “Modelos avançados de erros com google.rpc.Status” é grátis?
Sim — o texto completo de “Modelos avançados de erros com google.rpc.Status” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de gRPC & High Performance APIs, atualize para CoddyKit PRO. O curso de gRPC & High Performance APIs inclui 4 aulas no total.
O que vou aprender em “Modelos avançados de erros com google.rpc.Status”?
Vá além dos códigos de status simples anexando detalhes de erro estruturados e legíveis por máquina com o modelo google.rpc.Status e os tipos padrão de detalhes de erro. Você pratica gRPC & High Performance APIs com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.
Preciso ter experiência prévia para começar gRPC & High Performance APIs?
Nenhuma experiência prévia é necessária. gRPC & High Performance APIs no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 4 de 4.
Quanto tempo leva a aula “Modelos avançados de erros com google.rpc.Status”?
A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.
Posso escrever e executar código nesta aula de gRPC & High Performance APIs?
Sim. Cada aula de gRPC & High Performance APIs inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.
Todas as aulas deste curso
- Códigos de status e tratamento de erros
- Transmissão de metadados personalizados
- Contexto e prazos
- Modelos avançados de erros com google.rpc.Status