# GNews API 402 payment required plan error

## TL;DR
A 402 from GNews means the request needs a paid plan feature, usually more results, a wider date range, or higher quota than the current tier allows. This is billing, not a bug, so no retry or header fixes it. Either upgrade the plan, shrink the request to fit the current tier, or move that query to a source whose free tier covers it.

## The error
```text
HTTP 402 Payment Required
{"errors": ["Your current plan does not include this feature."]}
```

## When this helps
- GNews calls return 402 payment required
- a news pipeline needs features beyond the free tier
- deciding between upgrading and re-sourcing
- routing queries across news providers by tier

## When it doesn't
- the error is 429; that is quota, not plan
- you want the paid feature without paying; that is not available
- the key is invalid; that returns 401, not 402

## Works with
GNews API v4 as of 2026. Plan features are provider-side.

## Steps
### 1. Identify which feature tripped the paywall
```bash
K="apikey"
curl -s "https://gnews.io/api/v4/search?q=[topic]&lang=en&${K}=${GNEWS_KEY}" -o gnews.json -w "HTTP %{http_code}\n"
python3 -c "import json; print(json.load(open("gnews.json")))"
```
Expected: The 402 body naming the missing feature. Date-range search and large page sizes are the usual paywalled features.

### 2. Shrink the request to fit the current tier
```bash
K="apikey"
curl -s "https://gnews.io/api/v4/top-headlines?lang=en&${K}=${GNEWS_KEY}" -o gnews2.json -w "HTTP %{http_code}\n"
python3 -c "import json; d=json.load(open("gnews2.json")); print("articles:", d.get("totalArticles"))"
```
Expected: HTTP 200. Top-headlines and simple search usually fit free tiers; the paywalled features are the advanced ones.

### 3. Check usage against the plan dashboard
```python
import requests, os
r = requests.get("https://gnews.io/api/v4/usage", params={"apikey": os.environ["GNEWS_KEY"]}, timeout=20)
print(r.status_code)
print(str(r.json())[:200])
```
Expected: Usage numbers if the provider exposes them. Knowing the burn rate tells you whether to optimize or upgrade.

### 4. Route paywalled queries to a fitting source
```python
import json
routing = {"simple_search": "gnews free tier", "historical_search": "licensed news api", "top_headlines": "gnews free tier"}
open("news_routing.json", "w").write(json.dumps(routing, indent=2))
print("paywalled query types routed to a licensed source")
```
Expected: A routing table. Queries that need paid features go to the paid source; simple queries stay on the free tier.

## Other ways people phrase this
### gnews 402 plan error
Billing-gated features. Shrink the request or upgrade; there is no technical workaround.

### gnews free tier limit search
Free tiers cover basic search and headlines. Historical and bulk queries need paid tiers.

### payment required news api
The general case. Match the query to a tier that includes it.

## Why it happens
GNews tiers features by plan: free covers basic search while date ranges, large result sets, and high quotas are paid. A 402 is the billing gate, not a malfunction. Code cannot negotiate the tier; the request must fit the plan or the plan must change.

## Edge cases
- Plan changes can take minutes to propagate; wait before retesting after an upgrade.
- Caching paywalled responses aggressively stretches a paid tier further.
- Some providers offer academic or startup plans; ask before paying list price.
- Track which query types need paid features so the routing table stays accurate.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_2EFSs8IxeEbqAA4SouV-QQ