> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nordicfinancialnews.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Error handling

> Error format, status codes, and how to handle API errors.

The Nordic Financial News API uses [RFC 9457 Problem Details](https://www.rfc-editor.org/rfc/rfc9457) for all error responses. Every error includes a machine-readable `type` URI, a human-readable `title` and `detail`, and the HTTP `status` code.

## API error response format

All Nordic Financial News API errors return a JSON object with the following fields:

```json theme={"dark"}
{
  "type": "https://docs.nordicfinancialnews.com/problems/not-found",
  "title": "Resource not found",
  "status": 404,
  "detail": "No article found with id 'abc123'."
}
```

| Field    | Description                              |
| -------- | ---------------------------------------- |
| `type`   | URI identifying the error type           |
| `title`  | Short human-readable summary             |
| `status` | HTTP status code                         |
| `detail` | Specific explanation for this occurrence |

## HTTP status codes and common causes

| Code  | Meaning               | Common cause                            |
| ----- | --------------------- | --------------------------------------- |
| `400` | Bad request           | Invalid parameters or malformed request |
| `401` | Unauthorized          | Missing or invalid API key              |
| `403` | Forbidden             | API key lacks required scope            |
| `404` | Not found             | Resource does not exist                 |
| `429` | Too many requests     | Rate limit or monthly limit exceeded    |
| `500` | Internal server error | Unexpected server error                 |

## Error examples and how to fix them

### 400 Bad request

Returned when a request contains invalid parameters, such as an unrecognized filter value or a malformed date.

```json theme={"dark"}
{
  "type": "https://docs.nordicfinancialnews.com/problems/bad-request",
  "title": "Bad request",
  "status": 400,
  "detail": "Invalid value for 'content_type': 'blog'. Allowed values: news, analysis, press_release, market_commentary."
}
```

**How to fix:** Check the `detail` field for the specific validation error. Verify that query parameters match the expected types and allowed values documented in the [API reference](/api-reference/introduction).

### 401 Unauthorized

Returned when the `Authorization` header is missing, malformed, or contains an invalid API key.

```json theme={"dark"}
{
  "type": "https://docs.nordicfinancialnews.com/problems/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid or missing API key."
}
```

**How to fix:** Verify your API key is included as a Bearer token in the `Authorization` header (`Authorization: Bearer YOUR_API_KEY`). Check that the key is active in **Settings > API Keys**. API access is available on all plans.

### 403 Forbidden

Returned when your API key is valid but lacks the required scope for the requested resource.

```json theme={"dark"}
{
  "type": "https://docs.nordicfinancialnews.com/problems/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "API key lacks required scope: read:watchlist."
}
```

**How to fix:** Check which scopes are enabled on your API key in **Settings > API Keys**. Watchlist endpoints require the `read:watchlist` scope. See [API key scopes and permissions](/guides/authentication#api-key-scopes-and-permissions) for the full scope list.

### 404 Not found

Returned when the requested resource does not exist, either because the ID is wrong or the resource has been removed.

```json theme={"dark"}
{
  "type": "https://docs.nordicfinancialnews.com/problems/not-found",
  "title": "Resource not found",
  "status": 404,
  "detail": "No article found with id 'art_abc123def'."
}
```

**How to fix:** Verify the resource ID is correct. Article IDs start with `art_`, story IDs with `sty_`. For companies, you can use either the company ID or ticker symbol.

### 429 Too many requests

Returned when you exceed your hourly rate limit or monthly usage quota.

```json theme={"dark"}
{
  "type": "https://docs.nordicfinancialnews.com/problems/rate-limited",
  "title": "Too many requests",
  "status": 429,
  "detail": "Hourly rate limit exceeded."
}
```

**How to fix:** Check the `Retry-After` header for how many seconds to wait before retrying. Monitor the `X-RateLimit-Remaining` and `X-Monthly-Remaining` response headers to track your usage proactively. Check your current limits in [API key settings](https://nordicfinancialnews.com/settings/api_keys).

## How to handle rate limit errors

When you exceed a rate limit, the API response includes a `Retry-After` header indicating how many seconds to wait:

```http theme={"dark"}
HTTP/1.1 429 Too Many Requests
Retry-After: 60
```

Use these response headers on every request to monitor your usage before hitting a limit:

| Header                  | Description                             |
| ----------------------- | --------------------------------------- |
| `X-RateLimit-Remaining` | Requests remaining in the current hour  |
| `X-Monthly-Remaining`   | Requests remaining in the current month |

<Tip>
  `304 Not Modified` responses from [ETag caching](/guides/caching) do not count against your monthly quota. Use conditional requests to reduce your effective usage.
</Tip>

Error responses count toward your quota: any request that authenticates successfully consumes a monthly request, even if it returns a `404` or a validation error. See [what counts toward your quota](/guides/authentication#what-counts-toward-your-quota).

## How to trace requests with X-Request-Id

Every Nordic Financial News API response includes an `X-Request-Id` header with a unique identifier for that request. Include the `X-Request-Id` value when contacting [support](/support) to help diagnose issues with a specific request.

```http theme={"dark"}
X-Request-Id: req_7f3a2b1c-4d5e-6f7a-8b9c-0d1e2f3a4b5c
```