# Designing API Errors

DevFeed: [Designing API Errors](<https://devfeed.tech/articles/designing-api-errors-19054.md>)

Original publisher: [Read original article](<https://httptoolkit.com/blog/designing-api-errors/>)

Author: HTTP Toolkit; Phil Sturgeon

Published: 2024-09-09T15:30:00Z

Content type: article

Language: en

Sources: [HTTP Toolkit](<https://devfeed.tech/sources/http-toolkit.md>)

Topics: [API](<https://devfeed.tech/topics/api.md>), [HTTP](<https://devfeed.tech/topics/http.md>)

Tags: [api](<https://devfeed.tech/tags/api.md>), [apis](<https://devfeed.tech/tags/apis.md>), [developers](<https://devfeed.tech/tags/developers.md>), [errors](<https://devfeed.tech/tags/errors.md>), [http](<https://devfeed.tech/tags/http.md>), [standards](<https://devfeed.tech/tags/standards.md>)

## AI overview

The article explains how to design API errors by combining HTTP status codes with human-readable descriptions. It shows that status codes communicate broad categories and expected handling, while additional details help developers and users distinguish specific problems.

## Source excerpt

When everything goes smoothly with an API, life is pretty straightforward: you request a resource, and voilà, you get it. You trigger a procedure, and the API politely informs you it's all gone to plan. But what happens when something goes pear-shaped? Well, that's where things can get a bit tricky. HTTP Status Codes HTTP status codes are like a first aid kit: they're handy, but they won't fix everything. They give you a broad idea of what's gone wrong, which can help plenty of tools and developers make reasonable assumptions, like: 400 Bad Request: Report error to developers, something is broken. 401 Unauthorized: Might need to refresh a token, don't try again until you have. 404 Not Found: If accepting user input to lookup a resource then this isn't a problem, so don't worry about it. Just tell the user the thing they're looking for isn't there. 405 Method Not Allowed: Ahhhh panic, the API has changed or the client was built wrong. 429 Too Many Requests: Do not retry this request until after the rate limit is over or you'll DDoS the server and get banned. 501 Not Implemented: Oh heck you've gone live relying on an endpoint which isn't ready in production, alert everyone. 504 Gateway Timeout: Probably retry that one straight away as it's likely a network blip. HTTP status codes can convey a lot of assumptions, but they cannot possibly cover all situations, so it's important to add something for the human developers to see what's wrong. Written Description of the Problem Let's say you're building a carpooling app and you need to plan a trip between two places to find more riders. If the coordinates you provide are too close together, the API might respond with something like: HTTP/1.1 400 Bad Request { "error": "Too close for a carpool to be organized, suggest get out and walk." } This is a 400 Bad Request, but that's a pretty common error and a little more information needs to be conveyed, so a string has been added explaining the problem. Next a user tries to plan