Course outline

01 · HTTP & REST APIs

02 · Databases & Persistence

03 · Authentication & Authorization

04 · API Design & gRPC

05 · Caching, Queues & Background Jobs

06 · Production-Ready Services

07 · Advanced Auth & Tenant Security

08 · Performance & Caching at Scale

09 · Testing & Release Confidence

Stage 3 · Build

API Design & gRPC

Error Contracts

Standardize REST problem+json, gRPC status codes, validation errors, and correlation IDs.

7 min readBuilding Backend ApplicationsBuild

Why Error Contracts

Inconsistent error responses make API integration painful. Clients cannot reliably parse errors or determine the correct retry strategy. A consistent error contract lets clients handle errors programmatically.

problem+json

RFC 7807 defines a standard format for HTTP API errors. It includes a type URI, title, status code, detail message, and optional extensions. Use this format for all REST API errors.

Goproblem-details-implementation.go

29 linesLn 1, Col 1Go

The Content-Type for problem responses is application/problem+json. This lets clients distinguish between successful JSON responses and error responses.

gRPC Status Codes

Code	Name	Use Case
0	OK	Success
3	INVALID_ARGUMENT	Bad request parameters
4	DEADLINE_EXCEEDED	Request timed out
5	NOT_FOUND	Resource does not exist
6	ALREADY_EXISTS	Duplicate creation
7	PERMISSION_DENIED	Authorization failure
13	INTERNAL	Server error
14	UNAVAILABLE	Service down
16	UNAUTHENTICATED	Missing or invalid credentials

Goreturning-grpc-errors.go

21 linesLn 1, Col 1Go

Map application errors to gRPC status codes. Use status.Error for simple messages and status.Errorf for formatted messages. Clients use the code to determine retry behavior.

Validation Errors

Gostructured-validation-errors.go

26 linesLn 1, Col 1Go

Include all validation errors in a single response. Clients can display all errors at once instead of fixing them one at a time. Use 422 Unprocessable Entity.

Correlation IDs

Goincluding-correlation-ids-in-errors.go

16 linesLn 1, Col 1Go

Include the correlation ID in both the response header and the problem body. Support engineers can use it to trace the request across logs.

Error Middleware

Gocentralized-error-handling.go

20 linesLn 1, Col 1Go

Centralize error handling in middleware. Handlers return errors, middleware converts them to proper HTTP responses. This ensures consistent error format across all endpoints.

Error contracts are API contracts

Treat error responses as part of your API contract. Document error codes, status codes, and response shapes. Breaking error responses are breaking API changes.

Mark this lesson complete to store local progress and unlock a cleaner resume path the next time you visit.