Skip to main content
This guide explains how to interpret and resolve common errors you may encounter while using News API. For a quick reference of all error codes, see Errors.

Error response structure

When an error occurs, the API returns a JSON object with three fields:
string
required
Human-readable description of the error.
integer
required
HTTP status code.
string
required
Short label corresponding to the status code.
Example:

Common errors and solutions

Authentication failed, usually due to an invalid or missing API key.Example:
Solution:
  1. Verify that you are using the correct API key.
  2. Ensure the API key is passed in the x-api-token header, not x-api-key.
  3. Check your API key status by calling the /subscription endpoint.
The request is valid, but the server refuses to process it. Common causes: the requested resource requires permissions your plan doesn’t include, a parameter isn’t available on your plan, or the date range exceeds your plan’s allowed history period.Example:
Solution:
  1. Verify your plan includes the parameters and features you’re using.
  2. Check for typos in parameter names.
  3. Ensure your date range stays within your plan’s history limit.
  4. If you believe you should have access, contact support.
The server couldn’t complete the request within the 30-second timeout. Most commonly caused by complex queries over long time ranges that span multiple monthly indexes.Example:
Solution:
  1. Break the query into smaller time chunks — monthly ranges work best.
  2. Reduce nested boolean logic and NEAR operators in a single query.
  3. Lower page_size (try 100 instead of 1000 for complex queries).
  4. Implement retry logic with exponential backoff.
For historical data queries specifically, see Working with historical data.
The server understood the request but can’t process it due to invalid input.Example:
Solution:
  1. Check all parameter names, formats, and values against the API Reference.
  2. Ensure from_ is earlier than to_.
  3. Verify date strings follow the expected format.
You’ve exceeded the rate limit for concurrent API requests.Example:
Solution:
  1. Add delays between requests or implement a request queue.
  2. Use exponential backoff when retrying.
  3. Check your plan’s concurrency limits in Subscription plans.
A non-standard code for client-side errors that don’t fit standard HTTP status codes. Typically indicates a missing required field or malformed parameter.Example:
Solution:
  1. Check your request payload for missing required fields.
  2. Verify all parameter types match the API specification.
  3. Review the API Reference for the correct request format.
An unexpected server-side condition. Can also be triggered by a malformed request payload — the API returns a generic 500 rather than a validation error for certain malformed inputs.
This error often doesn’t return a JSON response body. You may see a generic error page or a connection error instead.
Solution:
  1. Validate your JSON payload before sending — check for syntax errors like missing brackets or trailing commas.
  2. Wait a few minutes and retry.
  3. Check the NewsCatcher status page for any known incidents.
  4. If the problem persists, contact support with your request details and correlation ID.

Troubleshooting with correlation IDs

Every API response includes a correlation-id header. Always include it when contacting support — it helps us locate your exact request in the logs.
For a full guide on extracting and using correlation IDs, see Request tracing with correlation IDs.

Best practices

  • Inspect the status code first. The code narrows the problem space before you read the message.
  • Implement structured error handling. Use try-catch blocks and log both the status code and message for every failed request.
  • Use exponential backoff for transient errors. Apply it to 429 and 408 — not to 401, 403, or 422, which indicate problems that won’t resolve on retry.
  • Validate before sending. Check parameter formats, required fields, and date ranges client-side to avoid round-trips on predictable errors.
  • Protect your API key. Store it in environment variables, not in source code.

See also