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 did not receive a complete request message within the default timeout of 30 seconds. This could be due to slow network connections, high server load, or client-side delays.

Example:

{
  "message": "Request timed out after 30 seconds",
  "status_code": 408,
  "status": "Request timeout"
}

Solution:

  1. Ensure your network connection is stable and fast enough to complete the request in a timely manner.
  2. If possible, reduce the size of your request payload to minimize the time needed to send the request to the server.
  3. Narrow your search query by avoiding the * wildcard in the q parameter and using filters like from_, to_, or sources.
  4. Implement retry logic with exponential backoff to handle temporary network issues causing timeouts.

​
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.

​
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

Was this page helpful?

Check sources coverageReport bugs