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

# Report bugs

> How to report bugs and issues with the NewsCatcher APIs

This guide explains how to effectively report bugs and issues with the
NewsCatcher APIs to ensure quick resolution and improve your experience.

## Before you report

Before submitting a bug report, take the following steps to ensure efficient
resolution:

* **Check documentation**: Review the [API Reference](/news-api/api-reference/search/search-articles-post) to
  verify you're using parameters correctly and that you understand expected
  behaviors.

* **Verify API usage**: Double-check that you're using the correct headers,
  parameters, and payload formats according to our documentation.

* **Check status page**: Visit our
  [status page](https://status.newscatcherapi.com) to see if there are any
  known issues or maintenance activities affecting the service.

* **Try our debugging tools**: Use our
  [Postman collections](https://www.postman.com/newscatcherapi/newscatcher-public-workspace/overview)
  or the API playground in our documentation to verify if the issue can be
  reproduced with different tools.

* **Examine your code**: Double-check your implementation to ensure the issue
  isn't in your integration code.

<Tip>
  Many reported "bugs" turn out to be integration issues that can be resolved
  through proper configuration or implementation. Testing with Postman often
  helps identify these cases quickly.
</Tip>

## Where to report bugs

You can report bugs through the following official channels:

<CardGroup cols={2}>
  <Card title="Customer Portal" icon="ticket" href="https://support.newscatcherapi.com">
    Our preferred channel for bug reports with structured templates and ticket
    tracking
  </Card>

  <Card title="Email Support" icon="envelope" href="mailto:support@newscatcherapi.com">
    Alternative channel for bug reports and general support
  </Card>

  <Card title="Dedicated Slack" icon="slack">
    For eligible customers with dedicated Slack channel access (based on plan
    tier)
  </Card>

  <Card title="GitHub Issues" icon="github" href="https://github.com/Newscatcher/newscatcher-python/issues">
    Review the current issues and open a new one if needed (for SDK-related bugs
    only)
  </Card>
</CardGroup>

<Info>
  Our Customer Portal is the recommended channel as it automatically creates
  tickets in our internal tracking system, allowing for faster processing and
  resolution.
</Info>

## How to report effectively

When reporting a bug, include the following information to help us identify and
fix the issue quickly:

<Steps>
  <Step title="Include the correlation ID">
    <Info>
      Every API response includes a unique `correlation-id` in the headers. This ID
      is essential for us to trace your request through our system.
    </Info>

    Here's how to find it:

    <CodeGroup>
      ```bash Terminal theme={null}
      curl -i https://v3-api.newscatcherapi.com/api/search
      # Look for: correlation-id: 2697cebe-6f5c-46e0-9b99-81e8abe55522
      ```

      ```javascript JavaScript theme={null}
      // After making a request
      console.log(response.headers.get("correlation-id"));
      ```

      ```python Python theme={null}
      # After making a request
      print(response.headers['correlation-id'])
      ```
    </CodeGroup>
  </Step>

  <Step title="Describe what happened vs. what you expected">
    Include a brief description of the following:

    * What you were trying to do
    * What actually happened
    * What you expected to happen instead
  </Step>

  <Step title="Provide request and response details">
    Provide the following information to reproduce the issue:

    * API endpoint and method (`GET`/`POST`)
    * Request parameters or payload
    * Error message and status code
  </Step>
</Steps>

### Report template

Use this template when filing your report. It covers everything from the steps above.

<Expandable title="the bug report template">
  ```text theme={null}
  ## Bug description
  [Brief description of the issue]

  ## Correlation ID
  correlation-id: [ID from response headers]

  ## Request details
  - Endpoint: [for example, /v3/search]
  - Method: [GET/POST]
  - Parameters/Body: [Key details]

  ## Response
  - Status Code: [for example, 500]
  - Error Message: [If applicable]

  ## Expected behavior
  [What you expected to happen]

  ## Environment
  - Language/SDK: [for example, Python 3.9, newscatcher-python 1.2.0]
  ```

  <Tip>If possible, attach relevant screenshots that show the issue.</Tip>
</Expandable>

## Common issues and solutions

Before reporting a bug, check if your issue matches one of these common
scenarios:

### Using incorrect authentication header

We use `x-api-token` for authentication, not `x-api-key`:

<CodeGroup>
  ```http Correct theme={null}
  GET /v3/search HTTP/1.1
  Host: api.newscatcherapi.com
  x-api-token: YOUR_API_KEY
  ```

  ```http Incorrect theme={null}
  GET /v3/search HTTP/1.1
  Host: api.newscatcherapi.com
  x-api-key: YOUR_API_KEY
  ```
</CodeGroup>

### Malformed JSON payload causing 500 errors

If you receive a `500 Internal Server Error`, check your request payload:

<CodeGroup>
  ```json Correct theme={null}
  {
    "q": "bitcoin",
    "from_": "30d",
    "countries": ["US", "CA"]
  }
  ```

  ```json Incorrect theme={null}
  {
    "q": "bitcoin",
    "from_": "30d",
    "countries": ["US", "CA"  // Missing closing bracket
  }
  ```
</CodeGroup>

<Info>
  For security reasons, our API may return a generic 500 error for certain
  malformed payloads instead of detailed validation errors. Always validate your
  JSON before sending.
</Info>

## Bug report lifecycle

1. **Ticket creation**: Your report is converted into a ticket in our internal
   tracking system.

2. **Initial assessment**: Our support team performs an initial assessment to
   determine severity and priority.

3. **Investigation**: Our engineering team uses the correlation ID to trace the
   issue through our logs and systems.

4. **Status updates**: We keep you informed about the progress of your bug
   report through the same channel you used to report it.

5. **Resolution**: Once resolved, we provide details about the fix and when
   you can expect it to be deployed.

## Issue priority and response times

Priority is determined by two factors: urgency (how quickly the issue affects
your operations) and impact (the scope and severity of the effect on service
functionality). Knowing these levels helps you set expectations for response and
resolution times.

### Priority levels

| Priority   | Description                                                                | Target Response Time | Target Resolution Time |
| ---------- | -------------------------------------------------------------------------- | -------------------- | ---------------------- |
| Priority 1 | Critical issue causing complete service unavailability with no workaround  | 1 hour               | Within 12 hours        |
| Priority 2 | Significant issue with major impact; service usable but seriously impaired | 4 hours              | 2 business days        |
| Priority 3 | Moderate issue with acceptable workarounds available                       | 12 hours             | 5 business days        |
| Priority 4 | Minor issue with minimal impact                                            | 1 business day       | Planned                |

<Warning>
  Priority 1 issues should be reported by phone in addition to creating a ticket
  to ensure immediate attention. Standard support hours are 8am–5pm on business
  days in your principal location.
</Warning>

When reporting a bug, you can suggest a priority level based on the criteria
above, but our support team makes the final determination after a technical
assessment.

## Debugging tools

We provide several tools to help you debug issues before reporting them:

<CardGroup cols={2}>
  <Card title="Postman Collections" icon="globe" href="https://www.postman.com/newscatcherapi/newscatcher-public-workspace/overview">
    Pre-configured request collections for all our APIs with examples
  </Card>

  <Card title="API Playground" icon="flask" href="/news-api/api-reference/search/search-articles-post">
    Interactive API testing tool available directly in our documentation
  </Card>

  <Card title="Documentation AI Assistant" icon="robot">
    To use our AI chat assistant, type your question in the search bar (⌘K)
  </Card>

  <Card title="Status Page" icon="signal" href="https://status.newscatcherapi.com">
    Real-time service status and incident history
  </Card>
</CardGroup>

## See also

* [Error handling](/news-api/troubleshooting/error-handling)
* [Request tracing with correlation IDs](/news-api/troubleshooting/request-tracing-correlation-ids)
* [API error codes](/news-api/api-reference/errors)