API Error Handling
Error shapes, retryability signals and machine-readable causes.
3 to work through
-
intermediate
A platform's plugin API returns generic 500 errors when anything goes wrong. Developers cannot tell whether to retry, fix their code, or contact support. Redesign the error model.
2 min answer -
intermediate
A public API's errors are a mixture of HTTP status codes, free-text messages and inconsistent bodies. Design an error contract that integrators can automate against, and explain what each part is for.
2 min answer -
advanced
A shipping aggregator integrates dozens of carriers whose APIs report failures inconsistently - some with HTTP codes, some with 200 and an error body, some with a timeout that means success. How should errors be modelled?
2 min answer
4 terms in this topic
API Error Design
Returning failures in a consistent machine-readable structure that tells a client what went wrong, whether to retry, and what to do about it.
patternOutcome Certainty Taxonomy
Classifying every external response into definitely-failed-retryable, definitely-failed-terminal, definitely-succeeded, or unknown - and giving the f…
protocolProblem Details
A standard JSON structure for HTTP error responses, giving machine-readable type, human-readable detail, and room for extensions.
conceptRetryable Error
An error whose cause may resolve on its own, which a client may safely attempt again — as distinct from one that will fail identically.
Neighbouring topics
API & Integration
General material on integrating systems through contracts.
REST Design
Resources, uniform methods, status codes and statelessness.
GraphQL
Client-specified queries, N+1 resolution and query-cost control.
gRPC APIs
Contract-first RPC, generated clients and protobuf compatibility rules.
Webhooks
Push callbacks, signature verification, ordering and at-least-once delivery.
API Versioning
URL, header and account-pinned versioning, and who carries the burden.
Backward Compatibility
Which changes are safe, and how to make breakage a build failure.
Contract Testing
Verifying what consumers actually rely on, without a shared environment.
API Documentation
OpenAPI as a machine-checked contract rather than as prose.
Rate Limiting
Algorithms, shared counters, and signalling rejection properly.
Idempotency Keys
Client-generated keys stored atomically with the operation they guard.
Pagination & Filtering
Offset versus cursor, stable ordering and unbounded result sets.
Event-Driven Integration
Publishing facts rather than commands, and versioning event schemas.
Message Formats
JSON, Protobuf, Avro — schema evolution and payload economics.
Schema Registry
Enforcing compatibility on events the way CI enforces it on code.
Integration Patterns
Routers, translators, splitters, aggregators and dead letter channels.
Legacy Integration
Reaching systems that cannot change, without importing their model.
Partner & B2B Integration
External contracts, onboarding, sandboxes and long deprecation windows.
APIs as Products
Ownership, lifecycle, deprecation policy and developer experience.