From 15d1070dd235156f7abdefa10faa823556aa1fcf Mon Sep 17 00:00:00 2001 From: Gregory Oschwald Date: Fri, 26 Jun 2026 20:12:43 +0000 Subject: [PATCH 1/2] 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 29d9ae74497d71676dfe2a759fbea3e5173b4ce2 Mon Sep 17 00:00:00 2001 From: Gregory Oschwald Date: Fri, 26 Jun 2026 20:15:50 +0000 Subject: [PATCH 2/2] 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 | 22 ++++++++++++++++++++++ 2 files changed, 42 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..8a8f8bb82 100644 --- a/content/minfraud/release-notes/2026.md +++ b/content/minfraud/release-notes/2026.md @@ -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. {{}} +{{< 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 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