Error Handling

All errors from this API follow a consistent JSON format. Understanding the error responses helps you build resilient integrations.

Error Response Format

Every error response uses this structure:

{
  "detail": "Human-readable error message describing what went wrong"
}

The detail field is always a string containing a description of the problem.

HTTP Status Codes

Status Code	Meaning	When It Happens
200 OK	Success	The request was processed successfully
400 Bad Request	Invalid parameters	A required query parameter is missing, a value is out of range, or the value is not in the allowed set
401 Unauthorized	Missing authentication	The required RapidAPI authentication headers are not present
403 Forbidden	Invalid authentication	The request did not originate from the RapidAPI gateway
503 Service Unavailable	Backend failure	The search backend is unreachable, the search failed, or the service cannot process the request

Common Errors and Fixes

400 Bad Request — Missing Required Parameter

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

Cause: A required query parameter was omitted.

Fix: Check the endpoint documentation for required parameters and include all of them in your request URL.

400 Bad Request — Invalid Parameter Value

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

Cause: A parameter value is not in the allowed set (for example, an invalid timeframe value).

Fix: Use only the values listed in the endpoint documentation.

401 Unauthorized

{
  "detail": "Missing authentication header"
}

Cause: The x-rapidapi-key and x-rapidapi-host headers were not included in the request.

Fix: Add both headers. See Authentication for details on where to find your RapidAPI key.

403 Forbidden

{
  "detail": "Invalid proxy secret"
}

Cause: The request did not pass through the RapidAPI gateway. This typically happens when calling the API URL directly instead of through RapidAPI's infrastructure.

Fix: Ensure you are sending requests to https://fast-news-with-previews.p.rapidapi.com with the x-rapidapi-key header from your RapidAPI dashboard.

503 Service Unavailable

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

Cause: The underlying search backend is unreachable or returned an error.

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

Validation Rules Summary

These validation rules are enforced on all request parameters:

Rule	Parameters Affected
Required (must be present)	topic on /news, language on /news and /news/trending, topic1 on /news/topic, query on /news/local
Min length 1	All string parameters
Max length 100	topic, query
Max length 5	geo, language
Min length 2	language (when required)
Min 1, Max 100	limit, quantity
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

Best Practices

• Always check the HTTP status code before parsing the response body. A 200 response contains your data; anything else contains an error in the detail field.
• Validate your parameters client-side before sending requests to avoid unnecessary 400 errors.
• For 503 errors, implement retry with exponential backoff (start with 1 second, double on each retry, up to a maximum).
• Log the full detail message when debugging — it contains specific information about what went wrong.