Shippo · 2018
Created the error codes, messages, mapping, and API documentation for Manifest errors across 40+ shipping carriers.
1
Problem
Shippo offers an API that connects to over forty shipping carriers around the world. The primary product challenge is creating a generic abstraction layer that works across 40+ different web services and APIs.
In other words, how do you build the simplest, easiest API that doesn't require the developer to understand all the details of the carrier's own API?
Whenever a new, high-value customer started integrating our API, I'd join a Slack channel with their engineering team to hear real-time feedback, blockers, and suggestions. Shippo's lack of documented error messages was a recurring complaint.
2
Solution
I led the first effort to establish standardized API error messaging.
Previously, the Shippo API passed the carrier's response verbatim. That could range from a useless numeric code like "120121" to a message that referenced a field in the carrier's own schema, but not the name of that field in the Shippo API — e.g. "1459 The Reason for Export code value is not valid."
3
Results
manifest endpoint errors, many of which could be reused by other endpoints
4
Bonus
I also established the guidelines for creating new error codes and message values.
[API_object_name_problem_affected_field]