Error Handling

All errors follow a consistent JSON format. Check the HTTP status code first — 200 means success, anything else means the response body contains an error.

Error Format

{
  "detail": "Description of what went wrong"
}

The detail field is always a human-readable string explaining the problem.

Status Codes

Code	Meaning	When It Happens
200	Success	Request processed normally
400	Bad Request	Missing or invalid parameter
401	Unauthorized	Missing RapidAPI auth headers
403	Forbidden	Request not sent through RapidAPI gateway
503	Unavailable	Search backend unreachable

400 Bad Request

The most common error. Caused by a missing required parameter or an invalid value.

{"detail": "Key: 'NewsRequest.Topic' Error:Field validation for 'Topic' failed on the 'required' tag"}

{"detail": "Key: 'NewsRequest.Timeframe' Error:Field validation for 'Timeframe' failed on the 'oneof' tag"}

Fix: Check the endpoint docs for required parameters and accepted values.

401 Unauthorized

{"detail": "Missing authentication header"}

Fix: Add both x-rapidapi-key and x-rapidapi-host headers. See authentication.

403 Forbidden

{"detail": "Invalid proxy secret"}

Fix: Send requests to https://fast-news-with-previews.p.rapidapi.com through RapidAPI, not to a direct backend URL.

503 Service Unavailable

{"detail": "News service temporarily unavailable"}

Fix: Retry after a short delay. The API uses multiple backend instances with automatic fallback.

Best Practices

• Always check the HTTP status code before parsing the body
• Validate parameters client-side to avoid unnecessary 400 errors
• For 503 errors, use exponential backoff (1s, 2s, 4s, up to a max)
• Log the full detail message when debugging — it contains specific information about the failure

Validation Rules

Rule	Applies To
Required	topic on /news and /news/advanced, language on /news, /news/trending, /news/advanced, topic1 on /news/topic, query on /news/local
Min length 1	All string parameters
Min length 2	language (when required)
Max length 100	topic, query
Max length 5	geo, language
Max length 500	source, exclude_source
Range 1-100	limit
Allowed values	timeframe: last_1h, last_24h, last_48h, last_7d, last_30d, anytime
Allowed values	topic1/topic2: world, national, business, technology, entertainment, sports, science, health, politics, economy, environment
Allowed values	sort: published_at_desc, published_at_asc, title_asc, title_desc