Application Programming Interfaces, or APIs, are used widely across the internet. From connecting to Google Maps and making online payments to running video conferencing, organisations and individuals use APIs almost every second. They are powerful, but anyone who works with them runs into errors that are a headache to deal with.
This article goes through the most common REST API errors, what each HTTP status code means, why it happens and how to fix it. We also look at the tools and steps you can use to debug a failing request.
Table of Contents
A REST API error is the server's way of telling you that your request could not be processed as expected. Every response carries an HTTP status code, and that code tells you what happened. Codes in the 2xx range mean success. The ones that cause trouble fall into two families:
Because REST runs over HTTP request and response cycles rather than a persistent connection (the difference is covered in WebSocket vs HTTP), reading the status code is always the fastest first step. It points you straight at whether the fix is on your side or the provider's.
A 4xx code means the server received your request but could not accept it. In-house developers and API development services alike see these most often, and the fix is almost always in the request itself.
What it means: the server could not understand the request.
Common causes: malformed JSON, a missing or misspelt parameter, or the wrong Content-Type header.
How to fix: validate the request body and query parameters, confirm the Content-Type, and reproduce the call in Postman or curl to isolate the problem.
What it means: the server does not know who you are.
Common causes: a missing, expired or invalid token or API key.
How to fix: check your credentials, refresh the token, and confirm you are using the right key for the right environment (production versus sandbox).
What it means: the server knows who you are, but you are not allowed to access this resource.
Common causes: insufficient permissions or scopes, or an IP restriction.
How to fix: request the right scopes or access from the API provider and check the permissions attached to your key.
What it means: the endpoint or resource does not exist.
Common causes: a wrong URL or path, a deleted resource, or the wrong API version.
How to fix: check the endpoint path and base URL against the documentation and confirm the resource ID is correct.
What it means: the HTTP method is not supported on that endpoint.
Common causes: using GET where POST is required, or PUT where PATCH is expected.
How to fix: check the allowed methods in the documentation or read the Allow header in the response.
What it means: the client took too long to send the request.
Common causes: a slow network, an oversized payload, or a dropped connection. Lost or unacknowledged packets play a part here too, as explained in ACK and NACK.
How to fix: retry the request, reduce the payload size, and check your network connection.
What it means: the request conflicts with the current state of the resource.
Common causes: creating a duplicate record, or two edits colliding on the same resource.
How to fix: fetch the latest state of the resource first, resolve any duplicates, and use conditional requests where the API supports them.
What it means: the syntax is correct, but the data fails validation.
Common causes: a value that breaks a rule, such as an invalid email format or a number out of range.
How to fix: read the response body to see which field failed and correct the value.
What it means: you have hit the API's rate limit.
Common causes: too many calls inside the provider's time window.
How to fix: respect the Retry-After header, add exponential backoff between retries, cache responses where you can, and batch requests to cut the call count. Workloads that legitimately need higher throughput sometimes distribute calls across IP addresses using residential proxies.
A 5xx code means your request was valid but the server failed to handle it. There is usually little you can change in the request itself, so the right response is to retry sensibly and check the provider's status.
What it means: the server hit an unexpected condition and could not complete the request.
Common causes: an unhandled exception or a bug on the server side.
How to fix: retry after a short wait, log the request details and a timestamp, and contact the provider with those details if it persists. This is not a fault in your request.
What it means: a server acting as a gateway received an invalid response from an upstream server.
Common causes: an upstream service that is down, or a misconfigured proxy.
How to fix: retry the request and check the provider's status page for an active incident.
What it means: the server is temporarily unable to handle the request.
Common causes: maintenance or an overloaded server.
How to fix: respect the Retry-After header, retry with backoff, and check the status page.
What it means: a gateway did not get a timely response from an upstream server.
Common causes: a slow upstream service or network problems between servers. The underlying transport behaviour is covered in TCP and UDP protocols.
How to fix: retry the request, simplify or split heavy requests, and check the provider's status.
A consistent process turns most API errors into quick fixes. Work through these steps in order:
Strong habits from modern software development, such as validating inputs early and testing against the documentation, keep most of these errors rare in the first place. When you integrate with a specific provider, its API reference lists the exact error responses and codes to expect, for example the Digital Samba API reference.
An API error is a server's signal that your request could not be processed as expected. The HTTP status code in the response (like 400, 401 or 500) tells you what type of problem occurred, such as a missing parameter, an authentication issue or a server-side fault.
The first step is to read the HTTP status code: 4xx codes mean the client made a bad request, while 5xx codes mean the server could not fulfil it. Validate your URL, headers and request body, check your authentication credentials, and consult the API documentation. If the error is 5xx, contact the API provider, because the issue is on their side.
A 500 Internal Server Error means the server hit an unexpected condition and could not fulfil your request. It is a server-side fault, not a problem with your request. Try again after a few minutes, and if it persists, contact the API provider with the request details and a timestamp.
An invalid API key error is a form of 401 Unauthorised: the server does not recognise the credentials you sent. Check that you have copied the key correctly with no extra spaces, that you are using the right key for the right environment (production versus sandbox), and that the key has not been revoked or expired.
A 401 Unauthorised means the server does not know who you are, so your credentials are missing or invalid. A 403 Forbidden means the server knows who you are but you do not have permission to access this resource. Fix 401 by checking your credentials, and fix 403 by requesting access from the API provider.
An API timeout (408 Request Timeout or 504 Gateway Timeout) usually means the request took longer than the server's limit. Common causes are a slow network, an overloaded server, requests that return too much data, or rate-limit throttling. Retry with smaller batches, check your network, and confirm you are within the API's rate limits.