Error handling

The Nordic Financial News API uses RFC 9457 Problem Details 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:

{
  "type": "https://docs.nordicfinancialnews.com/problems/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "The requested resource could not be found",
  "instance": "urn:request:7f3a2b1c-4d5e-6f7a-8b9c-0d1e2f3a4b5c"
}

Field	Description
`type`	URI identifying the error type
`title`	Short human-readable summary
`status`	HTTP status code
`detail`	Specific explanation for this occurrence
`instance`	`urn:request:` followed by the request ID, which is the value the `X-Request-Id` response header carries

Some types add their own members. An invalid-parameter problem names the offending filter in parameter, except when the fields parameter is at fault, where it lists the names it did not recognize in unknown_fields instead. Branch your error handling on type, not on title or on the status code alone. The title is a human-readable summary that can differ between two responses sharing the same type, and a single type can be returned under more than one status code.

HTTP status codes and common causes

Code	Meaning	Common cause
`400`	Bad request	Invalid parameters or malformed request. See invalid parameter
`401`	Unauthorized	Missing or invalid API key. See authentication required
`403`	Forbidden	Your key lacks a scope (insufficient permissions) or your plan does not reach the content (plan limit exceeded)
`404`	Not found	Resource does not exist, or is not enabled for your key. See not found
`429`	Too many requests	Hourly rate limit exceeded, or monthly limit exceeded
`500`	Internal server error	Unexpected server error
`503`	Service unavailable	A semantic search could not be completed. See semantic search unavailable

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.

{
  "type": "https://docs.nordicfinancialnews.com/problems/invalid-parameter",
  "title": "Invalid parameter",
  "status": 400,
  "detail": "Unknown content type(s): blog. Valid values: news, analysis, press_release, market_commentary, market_news, trading_halt, trading_event, other",
  "parameter": "content_type",
  "instance": "urn:request:7f3a2b1c-4d5e-6f7a-8b9c-0d1e2f3a4b5c"
}

How to fix: Read parameter for the offending filter and detail for the accepted values. Verify that query parameters match the expected types and allowed values documented in the API reference. See invalid parameter for the full handling guidance. A filter that names companies, ticker or company, returns the more specific invalid-parameter type when a value does not resolve:

{
  "type": "https://docs.nordicfinancialnews.com/problems/invalid-parameter",
  "title": "Invalid parameter",
  "status": 400,
  "detail": "Unknown ticker(s): VOLVB, ericb",
  "parameter": "ticker",
  "instance": "urn:request:7f3a2b1c-4d5e-6f7a-8b9c-0d1e2f3a4b5c"
}

How to fix: The detail names every value that failed to resolve, exactly as you sent it. Look them up with GET /companies and correct or drop them. exchange, index, market, and domicile behave differently: an unrecognized value there never errors. It drops out of the filter, or returns an empty page when nothing in the filter matches. sector validates against a fixed list and returns this same error, listing the valid sectors.

401 Unauthorized

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

{
  "type": "https://docs.nordicfinancialnews.com/problems/auth-invalid",
  "title": "Authentication required",
  "status": 401,
  "detail": "Missing or invalid API key",
  "instance": "urn:request:7f3a2b1c-4d5e-6f7a-8b9c-0d1e2f3a4b5c"
}

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. The same detail is returned whether the key is missing, malformed, unknown or revoked, so check all four. See authentication required.

403 Forbidden

Returned when your API key is valid but is not permitted to make the request, either because it lacks the required scope or because it has an IP allowlist that excludes you.

{
  "type": "https://docs.nordicfinancialnews.com/problems/auth-insufficient",
  "title": "Insufficient permissions",
  "status": 403,
  "detail": "Valid API key but insufficient entitlements for this resource",
  "instance": "urn:request:7f3a2b1c-4d5e-6f7a-8b9c-0d1e2f3a4b5c"
}

How to fix: Check which scopes are enabled on your API key in Settings > API Keys, and check its IP allowlist. Watchlist endpoints require the read:watchlist scope. The response does not say which of the two failed. See insufficient permissions, and API key scopes and permissions for the full scope list. A 403 can also mean your plan does not reach the content, which is a different type with a different remedy. See plan limit exceeded.

404 Not found

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

{
  "type": "https://docs.nordicfinancialnews.com/problems/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "The requested resource could not be found",
  "instance": "urn:request:7f3a2b1c-4d5e-6f7a-8b9c-0d1e2f3a4b5c"
}

How to fix: Verify the resource ID is correct. For companies, you can use either the company ID or ticker symbol. detail never echoes the identifier you sent, so log the request URL yourself. An endpoint that is not enabled for your key also returns 404, so this is not proof the resource does not exist. See not found.

429 Too many requests

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

{
  "type": "https://docs.nordicfinancialnews.com/problems/rate-limit-exceeded",
  "title": "Rate limit exceeded",
  "status": 429,
  "detail": "Rate limit of 100 requests per hour exceeded. Please retry after 1847 seconds.",
  "instance": "urn:request:7f3a2b1c-4d5e-6f7a-8b9c-0d1e2f3a4b5c"
}

How to fix: Check the Retry-After header for how many seconds to wait before retrying. See rate limit exceeded for the full handling guidance. Monitor the X-RateLimit-Remaining and X-Monthly-Remaining response headers to track your usage proactively. Check your current limits in API key settings. Spending your monthly allowance returns the same status under a different type, and the two are not interchangeable:

{
  "type": "https://docs.nordicfinancialnews.com/problems/monthly-limit-exceeded",
  "title": "Monthly API request limit exceeded",
  "status": 429,
  "detail": "You have exceeded your monthly limit of 10000 API requests. Your limit resets on October 1, 2026."
}

How to fix: Nothing resets until the start of the next month, so Retry-After here can run to days. Read X-Monthly-Reset for the exact timestamp, and see monthly limit exceeded. Branching on type is what separates the two: an hourly limit clears on its own within the hour, a monthly one does not.

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/1.1 429 Too Many Requests
Retry-After: 60

Use these response headers 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, on a plan that caps them

A plan that meters usage rather than capping it sends X-Monthly-Usage instead. See rate limit headers.

304 Not Modified responses from ETag caching do not count against your monthly quota. Use conditional requests to reduce your effective usage.

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.

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 to help diagnose issues with a specific request.

X-Request-Id: 7f3a2b1c-4d5e-6f7a-8b9c-0d1e2f3a4b5c

Overview

Guides

API examples

CLI Tool

Model Context Protocol (MCP)

API error response format

HTTP status codes and common causes

Error examples and how to fix them

400 Bad request

401 Unauthorized

403 Forbidden

404 Not found

429 Too many requests

How to handle rate limit errors

How to trace requests with X-Request-Id

​API error response format

​HTTP status codes and common causes

​Error examples and how to fix them

​400 Bad request

​401 Unauthorized

​403 Forbidden

​404 Not found

​429 Too many requests

​How to handle rate limit errors

​How to trace requests with X-Request-Id

API error response format

HTTP status codes and common causes

Error examples and how to fix them

400 Bad request

401 Unauthorized

403 Forbidden

404 Not found

429 Too many requests

How to handle rate limit errors

How to trace requests with X-Request-Id