Call for a better error handling in APIs

"API calls are either successful or they fail" – at least that’s the concept current web protocols are based upon. But in the real world, it isn’t always that simple. There are use cases where a 3rd party system returns something that can’t be defined as a clear error, but returning a simple http status code of 200 OK without any additional information is also wrong. For those cases, every api provide has their own way of communicating to the client what has gone wrong in the backend. This is why we need to find a common way to communicate errors and especially those edge cases.

Transcript

1. Call for a better error handling in APIs
2. André Cedik · Developer Advocate shipcloud.io · andre@shipcloud.io shipcloud GmbH · Mittelweg 162 20148 Hamburg
3. API v2 • Incoporate learnings from more than 5 years • Easier integration in existing shop- / ERP-software • I18n • Returning translated strings • White label • Design first approach using OpenAPI
4. But most of all ...
5. ... better error communication!
6. shipcloud error communication
7. History of errors
8. Mariner 1 • Veered off course, because unscheduled maneuver • Steering unpossible • Missing hyphen in the code allowed transmission of incorrect guidance signals • Engineers hit self destruct button • $18 million error
9. ESA Ariane 5 Flight 501 • Reused software from Ariane 4 • Ariane 5 had faster engines • Software tried to push a 64-bit float into a signed 16- bit integer • Engineers hit self destruct button at 37 sec. into its maiden launch • $8 billion error
10. NASA Mars Climate Orbiter • Failed conversion from imperial units to metric • Send the orbiter too close to Mars‘ surface • $125 million error
11. Y2K Bug • Year numbers where saved with 2 digits (98,99,00,01) • No one knew what will happen when the year 2000 sets in • Since ‘00‘ also meant 1900 • $500 billion error
12. Pentium-FDIV-Bug • In 1994 Math Prof. Thomas R. Nicely reported the bug • Processor might return incorrect binary floating point results when dividing a number • Intel attributed error to missing entries in the lookup table • Tried to downplay the bug • Had to replace processors • $475 million error
13. Miscommunication
14. Mokusatsu - The World‘s Most Tragic Translation • Allied leaders called for Japan’s unconditional surrender • Japanese government said nothing while considering their options • PM Kantaro Suzuki was pressured for comment • said only one word "mokusatsu“ • Mistranslation leads to the dropping of the atomic bomb
15. Hawaii Missle Strike • In Jan. 2018 citizens of Hawaii were warned of an inbound ballistic missile strike • Turned out to be a false alert • Recording over phone „EXERCISE“ • Message with „THIS IS NOT A DRILL“ • Same UI used for drill and real alerts • No safeguards were in place • It took 38 minutes to retract the alert, because there was no response protocol for a false alert
16. Error handling in APIs Tools used at the moment
17. "Building fault-tolerant software boils down to detecting errors and doing something when errors are detected" Joe Armstrong, inventor of Erlang
18. http response status codes • Informational 1xx • Successful 2xx • 200 OK • Redirection 3xx • 301 Moved Permanently • Client Error 4xx • Server Error 5xx
19. http response status codes 4xx & 5xx • 400 Bad Request • 402 Payment Required • 403 Forbidden • 404 Not Found • 500 Internal Server Error • 502 Bad Gateway • 504 Gateway Timeout
20. Error handling in the body • Good: • Return complex structures • Get more specific about an error • Convey multiple errors • Bad: • Everyone has their own way of doing it • Therefore developers have to understand „the way“
21. Error handling in APIs The bad
22. shipcloud error communication
23. Sabre Dev Studio – error attribute • „error“ is always a string • Sometimes all Uppercase - > seems to be like an error code
24. Sabre Dev Studio – error attribute • „error“ is always a string • Sometimes all Uppercase - > seems to be like an error code • Sometimes it looks like an error trace
25. Sabre Dev Studio – code attribute • Sometimes it looks like a http response status code • Sometimes like an internal code • Same code used more than once • different error text • 102 • 111 • 404 • 500 • 700101 • 050002 • 060016 • 700202
26. Sabre Dev Studio – code attribute
27. Pitney Bowes • Each validated field has its own error code
28. Pitney Bowes • Each validated field has its own error code • "XXX is invalid, unsupported or missing“ • So what is it now?!?
29. Google Maps Geocoding API • Has a „status“ attribute • OK, ZERO_RESULTS, OVER_DAILY_LIMIT, OVER_QUERY_LIMIT, REQUEST_DENIED, INVALID_REQUEST, UNKNOWN_ERROR • INVALID_REQUEST = 400 Bad Request • OVER_QUERY_LIMIT = 200 OK
30. Google Drive API v3
31. Klarna
32. API Football
33. Error handling in APIs The good parts
34. squarespace
35. Facebook GraphAPI
36. Facebook Marketing API
37. Facebook Marketing API
38. Banks API
39. Figo.io
40. What we can do better
41. What‘s the problem? • „API calls either fail or are successful“ – Phil Sturgeon • „Soft errors“ • Not an exception type „crash“ • More like a warning
43. application/problem+json • RFC 7807 • Pros • Own content type • Predefined set of attributes • Extensible • Cons • Not encapsulated • Mixing with other content • Multi error handling just for one error type HTTP/1.1 403 Forbidden Content-Type: application/problem+json Content-Language: en { "type": "https://example.com/probs/out-of-credit", "title": "You do not have enough credit.", "detail": "Your current balance is 30, but that costs 50.", "instance": "/account/12345/msgs/abc", "balance": 30, "accounts": ["/account/12345", "/account/67890"] }
44. Warning header • RFC 7234 • Pros • You could handle „soft errors“ • Multiple warning header for multiple different errors • Cons • Complex data can‘t be returned • It‘s just a string HTTP/1.1 200 OK Date: Sat, 25 Aug 2012 23:34:45 GMT Warning: 112 - "network down" "Sat, 25 Aug 2012 23:34:45 GMT"
45. application/health+json • Internet Draft inadarei-api- health-check • Pros • „status“ attribute („pass“, „warn“, „error“) • Cons • Specific to health of an api • Overhead content HTTP/1.1 200 OK Content-Type: application/health+json { "status": "pass", "version": "1", "releaseId": "1.2.2", "notes": [""], "output": "", "serviceId": "f03e522f-1f44-4062-9b55-9587f91c9c41", "description": "health of authz service", "checks": { "cassandra:responseTime": [ { "componentId": "dfd6cf2b-1b6e-4412-a0b8-f6f7797a60d2", "componentType": "datastore", "observedValue": 250, "observedUnit": "ms", "status": "pass", "affectedEndpoints" : [ "/users/{userId}", "/customers/{customerId}/status", "/shopping/{anything}" ], "time": "2018-01-17T03:36:48Z", "output": "" }
46. application/vnd.api+json • JSON:API standard • Pros • Errors array to handle multiple errors • JSON pointers to show devs where an error has occurred • Cons • Everything is in errors object • „soft errors“ not possible
47. Best current practice • HTTP status code • Error object • Easy referencing of errors • „Code“ • „Subcode“ • Request IDs in the body • for easier request identification in support cases • Human readable message • In multiple languages
48. "An excellent error message is precise and lets the user know about the nature of the error so that they can figure their way out of it." Guy Levin, RestCase
49. Future of error handling in APIs A proposal
50. A proposal – to be discussed
51. A proposal – to be discussed • Responses in a new format • „data“ holds everything we‘d normally have in the root • „errors“ and „warnings“ give information about what happened • „errors“ and „warnings“ follow the RFC 7807 pattern
52. A proposal – to be discussed • „data“ is empty since no resource was created • Warnings possible if api supports this use case
53. Questions? Open Discussion @andrecedik
54. Sources • Atlas Agena with Mariner 1: NASA, https://commons.wikimedia.org/wiki/File:Atlas_Agena_with_Mariner_1.jpg • Ariane 5: DLR German Aerospace Center, https://www.flickr.com/photos/48213136@N06/8958839420 • Mars Climate Orbiter: NASA/JPL/Corby Waste, https://commons.wikimedia.org/wiki/File:Mars_Climate_Orbiter_2.jpg • Bug de l'an 2000: https://commons.wikimedia.org/wiki/File:Bug_de_l%27an_2000.jpg • Pentium: Konstantin Lanzet, https://commons.wikimedia.org/wiki/File:KL_Intel_Pentium_A80501.jpg • Hawaii Missle Alert SMS: https://twitter.com/tulsigabbard/status/952243723525677056