Practice API error handling vocabulary: error response shape, RFC 7807 Problem Details, idempotency key, Retry-After header, and surfacing upstream errors.
0 / 5 completed
1 / 5
What does RFC 7807 Problem Details define?
RFC 7807 defines a standard JSON (and XML) format for HTTP API errors. The 'type' is a URI identifying the error class, 'title' is a short description, 'status' is the HTTP status code, 'detail' is a human-readable explanation, and 'instance' is a URI for the specific occurrence.
2 / 5
What is an 'idempotency key' and why do APIs use it?
An idempotency key lets clients safely retry requests — especially important for payment APIs. If the same idempotency key is seen twice, the server returns the original response without processing the operation again, preventing double charges.
3 / 5
An API responds with a 'Retry-After' header. What should the client do?
The Retry-After header, typically sent with 429 Too Many Requests or 503 Service Unavailable, tells clients how long to wait before retrying. Clients should respect this value to avoid worsening rate limit or overload situations.
4 / 5
A colleague says 'we surface the upstream error.' What does this mean in an API context?
'Surfacing the upstream error' means the API relays the error received from a downstream service (like a payment processor or database) to the caller — either verbatim or lightly wrapped — rather than returning a generic 500 that hides the root cause.
5 / 5
What is the 'error response shape' in API design?
The error response shape is the agreed structure of all error payloads from an API. Consistency matters: clients should be able to handle any error from the API using the same parsing logic, regardless of which endpoint generated it.