Building a Semantic Search API with Spring Boot and pgvector - Part 3: The Embedding Layer.

Most semantic search tutorials treat embeddings as a single line of code — call the API, get a vector, store it. In practice, this is the part of the system where the most subtle bugs live. Not the kind that throw exceptions, but the kind that silently produces wrong similarity scores, wrong rankings, and search results that look correct but feel off. When I first built this service, I expected the difficult parts to be the database schema and the search query. Instead, most of the time went into the embedding layer. Small mistakes here don’t crash the application. They just make search behave strangely. Three things make this layer trickier than it looks. First, the API call is external. It can fail because of network issues, rate limits, or invalid requests, and the failure is not always obvious from the client side. Second, the response parsing has silent failure modes. A wrong field name, a missing element, or a partially parsed response can still produce a vector — just not the ri