This guide explains how to interpret and resolve common errors you may encounter while using the NewsCatcher News API v3. Understanding these errors can help you troubleshoot issues effectively and improve your integration with our API.

​
Error response structure

When an error occurs, the API returns a standard error response with the following structure:
  • message: A detailed description of the error.
  • status_code: The HTTP status code of the error.
  • status: A short description of the status code.
Example: 
{
  "message": "Invalid language",
  "status_code": 422,
  "status": "Validation error"
}

​
Common errors and solutions

Below are some common errors you might encounter and how to resolve them.

​
401 Unauthorized

Authentication failed, usually due to an invalid or missing API key. Example: 
{
  "message": "Invalid api key: INVALID_API_KEY",
  "status_code": 401,
  "status": "Unauthorized"
}
Solution:
  1. Verify that you are using the correct API key.
  2. Ensure you include the API key in the x-api-token header of your request.
  3. Check the status of your API key by requesting the /subscription endpoint.

​
403 Forbidden

The request is valid, but the server refuses action. This may occur if you lack the necessary permissions for a resource, use parameters that do not exist or are not allowed for your plan, or if the specified date range exceeds your plan’s allowed history period. Example: 
{
  "message": "Your plan request date range cannot be greater than 400 days",
  "status_code": 403,
  "status": "Forbidden"
}
Solution:
  1. Ensure your account has the necessary permissions for the requested operation.
  2. Review your parameters and verify they are allowed under your subscription plan.
  3. Check for any typos in the parameter names.
  4. Ensure the date range specified in your request does not exceed the allowed history period for your plan.
  5. If you believe you should have access, contact support to review your account permissions.

​
408 Request timeout

The server could not complete the request within the default timeout of 30 seconds. This is commonly caused by complex queries over long time ranges that require searching across multiple monthly indexes. Example: 
{
  "message": "Request timed out after 30 seconds",
  "status_code": 408,
  "status": "Request timeout"
}
Solution:
  1. Reduce time ranges: Break queries into smaller time chunks (ideally monthly) instead of searching across multiple years.
  2. Simplify complex queries: Reduce the number of NEAR operators, boolean logic, and nested conditions in a single query.
  3. Use smaller page sizes: Consider reducing page_size from 1000 to 100 for complex queries.
  4. Check network connection: Ensure your network connection is stable and fast enough.
  5. Implement retry logic: Use exponential backoff to handle temporary issues.
When working with historical data, see the guide for detailed best practices.

​
422 Validation error

The server understands the content type of the request but is unable to process the instructions contained in it due to invalid input. Example: 
{
  "message": "Invalid date format",
  "status_code": 422,
  "status": "Validation error"
}
Solution:
  1. Check the format and values of your request payload.
  2. Ensure that all required fields are present and correctly formatted.
  3. Follow the specific validation rules, such as ensuring the from_ date is not greater than the to_ date, and check for correct parameter formats as described in the documentation.

​
429 Too many requests

You have exceeded the rate limit for API requests. Example: 
{
  "message": "Max API requests concurrency reached",
  "status_code": 429,
  "status": "Too many requests"
}
Solution:
  1. Implement request throttling in your application to stay within rate limits.
  2. Use exponential backoff strategies when retrying requests.
  3. If you consistently hit rate limits, consider upgrading your plan to a higher limit.

​
499 Unknown status code

A non-standard HTTP status code used for various client-side errors that do not fit into standard HTTP status codes. Example: 
{
  "message": "str field required",
  "status_code": 499,
  "status": "Unknown status code"
}
Solution:
  1. Check your request payload for missing required fields.
  2. Ensure all parameters are correctly formatted and of the expected type.
  3. Review the API documentation for the correct format.

​
500 Internal server error

The server encountered an unexpected condition that prevented it from fulfilling the request. This is typically a server-side issue but could also result from a malformed or broken payload on the client side. Example: This error often does not return a JSON response; you might see a generic error page or a connection error. Solution:
  1. Wait a few minutes and try your request again.
  2. Check the NewsCatcher status page for any ongoing issues.
  3. Validate your payload before making the API request.
  4. If the problem continues and no known issues are reported, contact support with details of your request.

​
Troubleshooting with correlation IDs

All API responses include a correlation-id in the response headers. When reporting errors or contacting support, always include this ID to help us quickly identify and resolve your issue. 
correlation-id: 2697cebe-6f5c-46e0-9b99-81e8abe55522
For details on using correlation IDs for effective debugging, see our Request Tracing guide.

​
Best practices

  • Check the status code and error message: Always inspect the status code and error message in the API response to understand the nature of the error.
  • Implement error handling logic: Use try-catch blocks or equivalent mechanisms in your code to manage errors gracefully and log them for future analysis.
  • Use retry mechanisms with backoff: For transient errors like 429 (Too many requests) or 503 (Service unavailable), implement retries with exponential backoff to avoid overwhelming the server.
  • Validate input data: Ensure your data is correct and adheres to the API’s expected formats before making requests to reduce errors.
  • Monitor usage and error logs: Regularly check your API usage and error logs to identify and address recurring issues or patterns.
  • Follow security best practices: Protect your API key, validate user inputs, and monitor for any unauthorized usage to prevent security issues.
  • Stay updated: Periodically check the API documentation and status page for updates or changes.

​
Additional resources