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

Merged
oschwald merged 4 commits into from
Jun 30, 2026
Merged

Document HTTP status codes for legacy web services #1683

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
97d076b
Document HTTP status codes for legacy web services
oschwald Jun 26, 2026
eb2f176
Add release notes for legacy web service HTTP status codes
oschwald Jun 26, 2026
96d3d4f
Fix stale proxy MAX_REQUESTS_REACHED description
oschwald Jun 30, 2026
5c5732b
Update Elasticsearch GeoIP processor doc link
oschwald Jun 30, 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
2 changes: 1 addition & 1 deletion content/geoip/docs/databases.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -117,7 +117,7 @@ integrator for assistance. {{</ alert >}}
| Load balancer | NGINX | [ngx_http_geoip2_module](https://github.com/leev/ngx_http_geoip2_module) |
| Log Analyzer / Data Processing | Logstash | [Geoip filter plugin](https://www.elastic.co/docs/reference/logstash/plugins/plugins-filters-geoip) |
| Network Protocol Analyzer | Wireshark | [How To Use GeoIP With Wireshark](https://gitlab.com/wireshark/wireshark/-/wikis/HowToUseGeoIP) |
| Search | Elasticsearch | [GeoIP processor](https://www.elastic.co/docs/reference/enrich-processor/geoip-processor) |
| Search | Elasticsearch | [GeoIP processor](https://www.elastic.co/guide/en/elasticsearch/reference/8.19/geoip-processor.html) |
| Web server | Caddy | [caddy-geoip2](https://github.com/zhangjiayin/caddy-geoip2) |

## Command Line (mmdbinspect)
Expand Down
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
22 changes: 20 additions & 2 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`). |

@horgh horgh Jun 30, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Claude noted that this now contradicts lines 169-170.

The new status-code table says:

  • 401 Unauthorized → invalid license key → body INVALID_LICENSE_KEY
  • 402 Payment Required → out of queries → body MAX_REQUESTS_REACHED

But the file's pre-existing err documentation states:

▎ MAX_REQUESTS_REACHED – This error will be returned if your account is out of queries or if an invalid license key is provided.

So by the doc's own body-code list, an invalid license key yields MAX_REQUESTS_REACHED, which the new table maps to 402 — directly conflicting with the new 401 /
INVALID_LICENSE_KEY row. A customer building HTTP-layer routing (the whole point of this change) can't tell which status an invalid key actually produces.

@oschwald oschwald Jun 30, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Verified against the branch: the proxy service returns INVALID_LICENSE_KEY (HTTP 401) for an invalid/unknown key, not MAX_REQUESTS_REACHED. MAX_REQUESTS_REACHED (402) is only for out-of-queries.

— Claude

| `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 Expand Up @@ -148,8 +167,7 @@ All strings are returned as ASCII.
</li>
<li>
<code>MAX_REQUESTS_REACHED</code> – This error will be returned if
your account is out of queries or if an invalid license key is
provided.
your account is out of queries.
</li>
</ul>
</td>
Expand Down
24 changes: 24 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,30 @@ 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, and a valid IP that
isn't in our database still returns a `200 OK` status (with a warning in the
response body). Note that Proxy Detection now returns `400 Bad Request` for a
malformed request, such as a missing or invalid IP address, that previously
returned `200 OK`.

[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