Errors - newscatcher

NewsAPI v3 uses standard HTTP codes to indicate request success or failure. 2xx codes mean success, 4xx codes indicate user-related failures, and 5xx codes indicate infrastructure issues.

Common error codes

The following table provides a quick reference for the most common errors you might encounter while using the News API:

Status code	Status	Description	Quick solution
401	Unauthorized	Authentication failed. Typically due to an invalid or missing API key.	Verify the API key is correct and included in the `x-api-token` header. Check your API key status with `/subscription`.
403	Forbidden	Request is valid, but the server refuses action. Could be due to permission issues or plan limitations.	Check your plan permissions and parameter usage. Ensure date ranges are within allowed limits. Contact support if needed.
408	Request timeout	The server did not receive a complete request message within the default timeout of 30 seconds.	Check network connection, reduce request payload size if possible, narrow search query, implement retry logic.
422	Validation error	Server understands the request but cannot process it due to invalid input.	Ensure request data is correctly formatted and includes all required fields. Check date formats and parameter values.
429	Too many requests	Exceeded the allowed rate limit for API requests.	Implement request throttling and retry with exponential backoff. Consider upgrading your plan for higher limits.
499	Unknown status code	Client-side errors that do not fit standard HTTP status codes.	Check for missing fields or incorrect parameters. Follow the API Reference.
500	Internal server error	Unexpected server-side issue. Could be due to a malformed payload or temporary server issues.	Retry after a few minutes. Check the status page for known issues. Validate payload.

Quick tips

Always log errors for easy debugging.
Use exponential backoff for retries on rate-limited errors (429).
Validate request data against API documentation to avoid validation errors (422).

For detailed troubleshooting steps and best practices, refer to the Error handling guide.

⌘I