Semantic search unavailable

Problem type: https://docs.nordicfinancialnews.com/problems/semantic-unavailable

The API returns this problem type with HTTP 503 when a search using mode=semantic cannot be completed. Two things can cause it:

Your query could not be turned into an embedding, because the upstream call failed or did not finish inside its 3 second timeout.
The query embedded, but the vector search itself was cancelled for running past the database’s 15 second statement timeout. A broad filter over a large candidate set can reach it.

Only requests that ask for mode=semantic can return this. Keyword search is unaffected and stays available throughout.

Example response

{
  "type": "https://docs.nordicfinancialnews.com/problems/semantic-unavailable",
  "title": "Semantic search unavailable",
  "status": 503,
  "detail": "The search query could not be embedded. Retry shortly — no lexical fallback is applied.",
  "instance": "urn:request:7f3a2b1c-4d5e-6f7a-8b9c-0d1e2f3a4b5c"
}

The detail names the embedding in both cases, so it does not tell you which of the two you hit. You do not need to know in order to recover: the handling is the same either way.

Response headers

Header	Description
`Retry-After`	Seconds to wait before retrying. This problem type sets it to `5`

Why you get an error instead of keyword results

When semantic matching is unavailable, the API could quietly rank your results with keyword search instead. It deliberately does not. A silent fallback would return a differently ranked page under an identical request shape, with nothing in the response to say which ranking you received. That is difficult to detect and worse to debug, particularly for an agent that cannot tell the two apart. Failing explicitly means a 200 from a mode=semantic request always contains a genuine semantic result. Choosing keyword ranking is therefore yours to make, not something the API does on your behalf.

How to fix it

Wait the number of seconds in Retry-After and retry the same request. This condition is usually brief.

Python

import time
import requests

def semantic_search(url, params, headers, max_attempts=3):
    for attempt in range(max_attempts):
        response = requests.get(url, params=params, headers=headers)
        if response.status_code != 503:
            return response
        if attempt < max_attempts - 1:
            time.sleep(int(response.headers.get("Retry-After", 5)))

    # Semantic ranking is still unavailable. Fall back deliberately, dropping
    # mode so the request is ranked by keyword instead.
    keyword_params = {key: value for key, value in params.items() if key != "mode"}
    return requests.get(url, params=keyword_params, headers=headers)

If it persists past a few retries, drop mode=semantic and use keyword search until it recovers. Make that switch explicit in your own code so you always know which ranking produced the results you are holding.

Retrying safely

Successful query embeddings are cached for one hour, keyed on the query text after case folding and trimming, and shared across every surface. A query embedded within the last hour is normally served from that cache, so a retry of it does not re-embed. That removes one of the two causes, not both. The vector search still runs on every request, cache hit or not, so a repeat can still be cancelled and return this same error. A timed-out or failed embedding is not written to that cache, so a retry after an embedding failure genuinely re-attempts the call rather than replaying a stored failure. Each attempt draws on your semantic search allowance, including the ones that end in this error. The allowance is checked before the query is embedded, so a 503 costs you a call and so does every retry of it. Retry on Retry-After rather than in a tight loop, or you can turn one outage into a 429 on top of it.

Error handling for the full problem type list
Rate limit exceeded for the 429 returned when you exceed a request limit

Overview

Guides

API examples

CLI Tool

Model Context Protocol (MCP)

Example response

Response headers

Why you get an error instead of keyword results

How to fix it

Retrying safely

​Example response

​Response headers

​Why you get an error instead of keyword results

​How to fix it

​Retrying safely

​Related

Example response

Response headers

Why you get an error instead of keyword results

How to fix it

Retrying safely

Related