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
- What is a REST API error?
- Client-side errors (4xx)
- Server-side errors (5xx)
- How to debug a failing REST API call
- FAQ
What is a REST API error?
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:
- 4xx – client-side errors. Something was wrong with the request you sent, whether the request came from client software or a web browser.
- 5xx – server-side errors. Your request was fine, but the server could not fulfil it.
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.
Client-side errors (4xx)
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.
400 Bad Request
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.
401 Unauthorised
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).
403 Forbidden
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.
404 Not Found
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.
405 Method Not Allowed
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.
408 Request Timeout
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.
409 Conflict
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.
422 Unprocessable Entity
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.
429 Too Many Requests
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.
Server-side errors (5xx)
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.
500 Internal Server Error
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.
502 Bad Gateway
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.
503 Service Unavailable
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.
504 Gateway Timeout
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.
How to debug a failing REST API call
A consistent process turns most API errors into quick fixes. Work through these steps in order:
- Read the status code first. A 4xx points at your request, a 5xx points at the server.
- Inspect the full response body. Most APIs return an error message and an internal code that say exactly what went wrong.
- Check authentication. Confirm the token, API key and headers are present and valid.
- Reproduce the call in curl or Postman. This isolates the problem from your application code.
- Compare the request against the docs. Verify the URL, method, headers and body match what the endpoint expects.
- Check logs and monitoring. Server and gateway logs often reveal the root cause behind 5xx errors. Monitoring with AI anomaly detection can flag problems before they become significant and give you clearer visibility into API performance.
- Add retries with backoff. For 429, 503 and 504, retry on a delay and respect the Retry-After header rather than hammering the endpoint.
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.
FAQ
What does an API error mean?
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.
How do I fix an API error?
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.
What does a 500 API error mean?
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.
What does "invalid API key" mean?
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.
What is the difference between a 401 and 403 error?
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.
What causes an API timeout error?
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.
