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/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/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 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