> ## Documentation Index
> Fetch the complete documentation index at: https://newscatcherinc-docs.mintlify.site/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Interpret and handle API errors
> Understand and resolve common API errors in News API
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](/news-api/api-reference/errors).
## Error response structure
When an error occurs, the API returns a JSON object with three fields:
Human-readable description of the error.
HTTP status code.
Short label corresponding to the status code.
**Example:**
```json theme={null}
{
"message": "Invalid language",
"status_code": 422,
"status": "Validation error"
}
```
## Common errors and solutions
Authentication failed, usually due to an invalid or missing API key.
**Example:**
```json theme={null}
{
"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 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:**
```json theme={null}
{
"message": "Your plan request date range cannot be greater than 400 days",
"status_code": 403,
"status": "Forbidden"
}
```
**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](https://support.newscatcherapi.com).
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:**
```json theme={null}
{
"message": "Request timed out after 30 seconds",
"status_code": 408,
"status": "Request timeout"
}
```
**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](/news-api/guides-and-concepts/working-with-historical-data).
The server understood the request but can't process it due to invalid input.
**Example:**
```json theme={null}
{
"message": "Invalid date format",
"status_code": 422,
"status": "Validation error"
}
```
**Solution:**
1. Check all parameter names, formats, and values against the
[API Reference](/news-api/api-reference/search/search-articles-post).
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:**
```json theme={null}
{
"message": "Max API requests concurrency reached",
"status_code": 429,
"status": "Too many requests"
}
```
**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](/news-api/get-started/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:**
```json theme={null}
{
"message": "str field required",
"status_code": 499,
"status": "Unknown status code"
}
```
**Solution:**
1. Check your request payload for missing required fields.
2. Verify all parameter types match the API specification.
3. Review the [API Reference](/news-api/api-reference/search/search-articles-post)
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](https://status.newscatcherapi.com/) for
any known incidents.
4. If the problem persists, [contact support](https://support.newscatcherapi.com)
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.
```http theme={null}
correlation-id: 2697cebe-6f5c-46e0-9b99-81e8abe55522
```
For a full guide on extracting and using correlation IDs, see
[Request tracing with correlation IDs](/news-api/troubleshooting/request-tracing-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
* [Error codes](/news-api/api-reference/errors)
* [Rate limits](/news-api/api-reference/rate-limits)
* [Request tracing with correlation IDs](/news-api/troubleshooting/request-tracing-correlation-ids)