This week we’re pleased to ship some small changes to make our API responses a bit more precise when a problem is encountered. We’re doing this by changing a few of our HTTP status codes. We’ve gone over our SDKs to verify everything will continue to behave as expected, but we wanted to be sure and communicate these changes to the folks who’ve built such wonderful stuff on top of our API: you!
Better Than 400
Most of our errors return a status code of 400. This gets the point across, but it doesn’t necessarily identify the specific problem in such a way that an API user can react accordingly. A developer would need to examine the error message string, which is not nearly as simple as looking at the status code! To that end, here is the summary of changes:
- Events that are too large (either single or in batch) will now return a 413, representing “request entity too large.”
- Trying to delete a “keen” property will return a 403, representing “forbidden.”
- API endpoints that have been blocked due to lack of payment will return a 402, representing “payment required.”
And One More Thing: Query Timeouts
There’s one other change that’s a bit bigger. Query timeouts used to return a 400, but they now return a 503, representing a “gateway timeout.” This is a more correct answer because responses in the 4XX range signal that the client has made a mistake. Queries timing out are clearly a problem with Keen, and we should be making that clear in our responses!
Anything Else?
These changes improve our SDK’s ability to take proper action on certain failures, improve our ability to monitor patterns of status codes, and all-around make our API better. We look forward to continuing to improve our API both in capabilities and correctness in the future. If you have any questions, don’t hesitate to shoot an email to team@keen.io. Thanks for building things with Keen!
