Skip to content

Document HTTP status codes for legacy web services #1683

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
oschwald wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

Document HTTP status codes for legacy web services #1683

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
15d1070
Document HTTP status codes for legacy web services
oschwald Jun 26, 2026
29d9ae7
Add release notes for legacy web service HTTP status codes
oschwald Jun 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions content/geoip/docs/web-services/legacy.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,27 @@ geographically closest to you.
You must access this service via HTTPS. We require TLS 1.2 or greater for HTTPS
requests to our servers to keep your data secure.

### HTTP status codes

In addition to the error code returned in the response body, this service uses
the HTTP status code to indicate certain error conditions. This lets you act on
these conditions from the HTTP status code, for example in your monitoring or an
internal proxy, without parsing the response body.

| HTTP status | Condition |
| ---------------------- | ---------------------------------------------------------------------------------------- |
| `200 OK` | The request was processed. This includes successful lookups and the `IP_NOT_FOUND` case. |
| `400 Bad Request` | The request was malformed. |
| `401 Unauthorized` | The license key is missing or invalid (`LICENSE_REQUIRED` or `INVALID_LICENSE_KEY`). |
| `402 Payment Required` | Your account has run out of queries. |
| `403 Forbidden` | Your account does not have permission to use this service (`PERMISSION_REQUIRED`). |
| `5xx` | A server error occurred. |

The error code returned in the response body does not always match the HTTP
status code. When your account has run out of queries, the response body returns
the `INVALID_LICENSE_KEY` error code even though the HTTP status is `402 Payment
Required`. The `IP_NOT_FOUND` case returns a `200 OK` status.

### Output

All services return data as a set of comma-separated fields. The ISP name,
Expand Down
20 changes: 20 additions & 0 deletions content/geoip/release-notes/2026.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,26 @@ outputs: ['html', 'markdown']
[Sign up to be notified](https://comms.maxmind.com/geoip-rss-release-notes)
whenever a new GeoIP release note is posted. {{</ alert >}}

{{< release-note date="2026-06-30" title="GeoIP Legacy web service now returns HTTP status codes for errors" >}}

The GeoIP Legacy web service now returns meaningful HTTP status codes for error
conditions, so you can act on them in your monitoring or an internal proxy,
without parsing the response body:

- `400 Bad Request` for a malformed request
- `401 Unauthorized` for a missing or invalid license key
- `402 Payment Required` when your account is out of queries
- `403 Forbidden` when your account does not have permission to use the service
- `5xx` for a server error

The response body and its error-code strings are unchanged. The `IP_NOT_FOUND`
case continues to return a `200 OK` status to avoid breaking existing
integrations.

[See the GeoIP Legacy documentation for details.](/geoip/docs/web-services/legacy/#http-status-codes)

{{</ release-note >}}

{{< release-note date="2026-06-24" title="A number of networks now have an anonymizer confidence of 50" >}}

As of June 24, 2026, a number of networks have an `anonymizer_confidence` of 50,
Expand Down
20 changes: 20 additions & 0 deletions content/minfraud/minfraud-legacy.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,26 @@ HTTP, you will receive a `403 Forbidden` HTTP response.
We require TLS 1.2 or greater for all requests to our servers to keep your data
secure.

### HTTP status codes

In addition to the error code returned in the response body, this service uses
the HTTP status code to indicate certain error conditions. This lets you act on
these conditions from the HTTP status code, for example in your monitoring or an
internal proxy, without parsing the response body.

| HTTP status | Condition |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `200 OK` | The request was processed. This includes successful lookups and lookups that return a warning code in the response body. |
| `400 Bad Request` | The request was malformed. |
| `401 Unauthorized` | The license key is missing or invalid (`LICENSE_REQUIRED` or `INVALID_LICENSE_KEY`). |
| `402 Payment Required` | Your account is out of queries (`MAX_REQUESTS_REACHED`). |
| `403 Forbidden` | Your account does not have permission to use this service (`PERMISSION_REQUIRED`). |
| `5xx` | A server error occurred. |

Where applicable, the response body returns an `err` value with the relevant
error code. Warning conditions, including `IP_NOT_FOUND`, return a `200 OK`
status.

### Input

The minFraud API accepts input in a query string or as a form post
Expand Down
19 changes: 19 additions & 0 deletions content/minfraud/proxy-detection.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,25 @@ HTTP, you will receive a `403 Forbidden` HTTP response.
We require TLS 1.2 or greater for all requests to our servers to keep your data
secure.

## HTTP status codes

In addition to the error code returned in the `err` field of the response body,
this service uses the HTTP status code to indicate certain error conditions.
This lets you act on these conditions from the HTTP status code, for example in
your monitoring or an internal proxy, without parsing the response body.

| HTTP status | Condition |
| ---------------------- | ------------------------------------------------------------------------------------ |
| `200 OK` | The request was processed. |
| `400 Bad Request` | The request was malformed. |
| `401 Unauthorized` | The license key is missing or invalid (`LICENSE_REQUIRED` or `INVALID_LICENSE_KEY`). |
| `402 Payment Required` | Your account is out of queries (`MAX_REQUESTS_REACHED`). |
| `403 Forbidden` | Your account does not have permission to use this service (`PERMISSION_REQUIRED`). |
| `5xx` | A server error occurred. |

Where applicable, the response body returns an `err` value with the relevant
error code.

## Input

The API requires you to pass a set of parameters as an HTTP GET or POST. Results
Expand Down
22 changes: 22 additions & 0 deletions content/minfraud/release-notes/2026.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,28 @@ outputs: ['html', 'markdown']
[Sign up to be notified](https://comms.maxmind.com/minfraud-rss-release-notes)
whenever a new minFraud release note is posted. {{</ alert >}}

{{< release-note date="2026-06-30" title="minFraud Legacy and Proxy Detection web services now return HTTP status codes for errors" >}}

The minFraud Legacy and Proxy Detection web services now return meaningful HTTP
status codes for error conditions, so you can act on them in your monitoring or
an internal proxy, without parsing the response body:

- `400 Bad Request` for a malformed request
- `401 Unauthorized` for a missing or invalid license key
- `402 Payment Required` when your account is out of queries
- `403 Forbidden` when your account does not have permission to use the service
- `5xx` for a server error

The response body and its error-code strings are unchanged. Warning conditions,
including `IP_NOT_FOUND`, continue to return a `200 OK` status to avoid breaking
existing integrations.

[See the minFraud Legacy](/minfraud/minfraud-legacy/#http-status-codes) and
[Proxy Detection](/minfraud/proxy-detection/#http-status-codes) documentation
for details.

{{</ release-note >}}

{{< release-note date="2026-05-13" title="Improved readability of the risk reasons module within Transactions Details screen">}}

Based on user feedback, we have updated the risk reasons module within the
Expand Down
Loading