When you’re talking to an HTTP API, the server returns a status code signaling the status of your API request. Since status codes and error messages are determined by the API provider, they are only as meaningful and accurate as the API provider makes them. But most API providers follow the established industry standards grouping HTTP status codes into five categories according to the following scenarios:

• 100s Informational responses
• 200s Successful responses
• 300s Redirects
• 400s Client errors
• 500s Server errors

Let’s dive into status codes in the 400s indicating an issue with the client. As an API consumer, this means that you can update the API call to potentially solve the issue. Assuming the server returns reliable status messages, this is our first clue to tracking down the source of the bug.

Common client error codes

Here are some common client error codes in the 400s and what you can do when you encounter one of these errors:

• 400 Bad Request - This is the most general, catch-all status code for client errors. Look for syntax errors like typos or a malformed JSON body in your API call.
• 401 Unauthorized - Verify that you have valid authentication credentials for the target resource and check your syntax for header values
• 403 Forbidden - This means you do not have permission to access the resource. Check your permissions and scope to ensure you are authorized to access the resource.
• 418 I’m a Teapot - was created as an April Fool’s joke, but may indicate the request is one the provider does not want to handle, such as automated queries
• 429 Too Many Requests - check the documentation to understand the rate limits, or give it a break to try again later

There’s a number of other client errors defined in the industry standard, but it’s up to the API provider to implement status messages. If you’re unable to resolve the issue, check the API documentation for more clues as to how the provider has intended to handle those requests.

And if you want to try an interactive tutorial, check out Learn HTTP Status Codes with HTTP Cats 😺.