From 97d076b8fa8a5db50e4fd51b9da95deabd27cb93 Mon Sep 17 00:00:00 2001 From: Gregory Oschwald Date: Fri, 26 Jun 2026 20:12:43 +0000 Subject: [PATCH 1/4] Document HTTP status codes for legacy web services The minFraud Legacy, proxy detection, and GeoIP Legacy web services now return meaningful HTTP status codes for genuine errors: 400 for malformed requests, 401 for missing or invalid license keys, 402 when the account is out of queries, 403 for permission errors (PERMISSION_REQUIRED), and 5xx for server errors. IP-not-found and warning conditions continue to return 200, and the response body error codes are unchanged. Documenting these status codes lets customers act on them at the HTTP layer (for example, with edge or CDN rules) without parsing the response body. Co-Authored-By: Claude Opus 4.8 (1M context) --- content/geoip/docs/web-services/legacy.md | 21 +++++++++++++++++++++ content/minfraud/minfraud-legacy.md | 20 ++++++++++++++++++++ content/minfraud/proxy-detection.md | 19 +++++++++++++++++++ 3 files changed, 60 insertions(+) diff --git a/content/geoip/docs/web-services/legacy.md b/content/geoip/docs/web-services/legacy.md index c984289c8..c558b15be 100644 --- a/content/geoip/docs/web-services/legacy.md +++ b/content/geoip/docs/web-services/legacy.md @@ -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, diff --git a/content/minfraud/minfraud-legacy.md b/content/minfraud/minfraud-legacy.md index 8e5956b28..097d8dc69 100644 --- a/content/minfraud/minfraud-legacy.md +++ b/content/minfraud/minfraud-legacy.md @@ -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 diff --git a/content/minfraud/proxy-detection.md b/content/minfraud/proxy-detection.md index 375b1f373..1e1224d37 100644 --- a/content/minfraud/proxy-detection.md +++ b/content/minfraud/proxy-detection.md @@ -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 From eb2f17615c1094e4c1a4343a3d015919ce530043 Mon Sep 17 00:00:00 2001 From: Gregory Oschwald Date: Fri, 26 Jun 2026 20:15:50 +0000 Subject: [PATCH 2/4] Add release notes for legacy web service HTTP status codes Announce that the GeoIP Legacy, minFraud Legacy, and Proxy Detection web services now return meaningful HTTP status codes (400/401/402/403) for error conditions, while IP-not-found and the response body are unchanged. Co-Authored-By: Claude Opus 4.8 (1M context) --- content/geoip/release-notes/2026.md | 20 ++++++++++++++++++++ content/minfraud/release-notes/2026.md | 24 ++++++++++++++++++++++++ 2 files changed, 44 insertions(+) diff --git a/content/geoip/release-notes/2026.md b/content/geoip/release-notes/2026.md index db3ba966a..b006a73c5 100644 --- a/content/geoip/release-notes/2026.md +++ b/content/geoip/release-notes/2026.md @@ -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. {{}} +{{< 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 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, diff --git a/content/minfraud/release-notes/2026.md b/content/minfraud/release-notes/2026.md index abb4c4016..b320c0402 100644 --- a/content/minfraud/release-notes/2026.md +++ b/content/minfraud/release-notes/2026.md @@ -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. {{}} +{{< 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 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 From 96d3d4f390ed932de36efae05b8d50cdf03501ba Mon Sep 17 00:00:00 2001 From: Gregory Oschwald Date: Tue, 30 Jun 2026 18:04:27 +0000 Subject: [PATCH 3/4] Fix stale proxy MAX_REQUESTS_REACHED description The Proxy Detection err-field docs said MAX_REQUESTS_REACHED is returned "if your account is out of queries or if an invalid license key is provided." The service actually returns INVALID_LICENSE_KEY (HTTP 401) for an invalid key; MAX_REQUESTS_REACHED is only for out-of-queries (HTTP 402). The stray invalid-key clause contradicted the new HTTP status-code table, so drop it (matching minfraud-legacy.md). Co-Authored-By: Claude Opus 4.8 (1M context) --- content/minfraud/proxy-detection.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/content/minfraud/proxy-detection.md b/content/minfraud/proxy-detection.md index 1e1224d37..d30f30517 100644 --- a/content/minfraud/proxy-detection.md +++ b/content/minfraud/proxy-detection.md @@ -167,8 +167,7 @@ All strings are returned as ASCII.
  • MAX_REQUESTS_REACHED – 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.
    • From 5c5732b23f3764808d1692176c4e5bd6e2e8bb31 Mon Sep 17 00:00:00 2001 From: Gregory Oschwald Date: Tue, 30 Jun 2026 18:13:49 +0000 Subject: [PATCH 4/4] Update Elasticsearch GeoIP processor doc link The elastic.co reference URL for the GeoIP processor now 301-redirects to a page that 404s (Elastic is mid-migration), and the link checker (max_redirects = 0) rejects any redirect. Point to the version-pinned guide URL, which returns 200. Co-Authored-By: Claude Opus 4.8 (1M context) --- content/geoip/docs/databases.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/geoip/docs/databases.md b/content/geoip/docs/databases.md index 937d0556c..20cac56f4 100644 --- a/content/geoip/docs/databases.md +++ b/content/geoip/docs/databases.md @@ -117,7 +117,7 @@ integrator for assistance. {{}} | 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)