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 v3:
Status codeStatusDescriptionQuick solution
401UnauthorizedAuthentication 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.
403ForbiddenRequest 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.
408Request timeoutThe 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.
422Validation errorServer 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.
429Too many requestsExceeded the allowed rate limit for API requests.Implement request throttling and retry with exponential backoff. Consider upgrading your plan for higher limits.
499Unknown status codeClient-side errors that do not fit standard HTTP status codes.Check for missing fields or incorrect parameters. Follow the API Reference.
500Internal server errorUnexpected 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.