Skip to main content
ainative.axAX AUDIT
← All posts
ZeroDB Embeddings API: Stricter Model Validation and Honest Fallback Reporting
PLATFORM UPDATESNovember 16, 2026· 4 min read

ZeroDB Embeddings API: Stricter Model Validation and Honest Fallback Reporting

By Toby Morning
# ZeroDB Embeddings API: Stricter Model Validation and Honest Fallback Reporting If you build RAG pipelines, you know the sinking feeling of a bug you can't see: everything returns 200 OK, search quality quietly degrades, and nothing in your logs says why. This week we shipped two changes to the ZeroDB Embeddings API that eliminate an entire class of those invisible failures — stricter model name validation and honest reporting of which model actually served your request. ## What Changed ### 1. Unknown model names now fail fast with a 400 Previously, the `model` field on `POST /v1/{project_id}/embeddings/generate` (and the OpenAI-compatible `/v1/embeddings` route) accepted *any* string. A typo like `bge-small-en-v1` or a fabricated name like `some-made-up-model-xyz` didn't error — it silently fell through to whichever model in our fallback chain happened to respond. Your request succeeded, the response echoed your (unserved) model name back at you, and you had no way to know you weren't getting the model you asked for. Now, any name outside the real, known-servable set returns immediately: ```json { "detail": "Unknown embedding model 'some-made-up-model-xyz'. Known models: [...]" } ``` with a proper `400 Bad Request`. If the name is real, it resolves exactly as before. ### 2. Responses report the model that actually produced your vectors Our embedding stack has a resilience feature: if the primary model is unavailable (say, during a provider hiccup), the service automatically fails over to a same-dimension fallback model so your pipeline keeps running. That's a good thing — until the response lies about it. Before this change, the `model` field in the response always echoed the *requested* name, even when a fallback model actually produced the vectors. Now the `model` field reports the truth: ```json { "embeddings": [[0.123, -0.456, ...]], "model": "e5-large-v2", "dimensions": 1024, "count": 1, "processing_time_ms": 45.23 } ``` If you asked for `bge-m3` and it was briefly unavailable, the response tells you `e5-large-v2` served the request. All fallback models are dimensionally compatible (1024-dim), so your stored vectors stay consistent — but now you can *see* when a failover happened, log it, and alert on it. ## Why This Matters for RAG Pipelines Embedding model consistency is the foundation of vector search quality. If you store documents embedded with one model and query with another, similarity scores degrade in ways that are hard to diagnose — every individual request looks healthy, but recall quietly drops. The old behavior made this failure mode *invisible*: - A typo'd model name still "worked" — you got vectors from a different model than you thought - A failover still "worked" — the response claimed your requested model served it - Nothing in your observability stack could tell the difference The new behavior makes both cases explicit. Unknown names fail loudly. Failovers are reported honestly. Your monitoring can now catch model drift the moment it happens, instead of weeks later when someone notices search quality regressions. ## What You Should Check in Your Code If you're calling the embeddings API, audit two things: 1. **Hardcoded model strings.** If you're passing a model name that isn't in our known set — check the [Embeddings API documentation](https://docs.ainative.studio) for the current model list and aliases — your calls will now return 400 instead of silently succeeding. This is the change doing its job: that name was never a real model. 2. **Model field assertions.** If your tests or pipeline logic assert that the response `model` equals the requested model, relax that assertion or update it to expect the real serving model. Same-dimension failovers are a designed resilience feature, not an error. ## The Full Known Model Set Model names resolve through a documented alias table to the models our provider actually serves, with a fallback chain of dimensionally-compatible alternatives: - **384-dim**: `BAAI/bge-small-en-v1.5` (and aliases) → served by `all-mini-lm-l6-v2` - **1024-dim**: `BAAI/bge-large-en-v1.5` (and aliases) → served by `bge-m3`; fallback chain: `e5-large-v2`, `gte-large-en-v1.5`, `qwen3-embedding-0.6b` - Default: `bge-m3` (1024-dim) Everything remains **free** — no premium tiers, no upsells. ## Wrapping Up These two changes shipped in [v1.51](https://github.com/AINative-Studio/core) and are live in production. They're part of our ongoing effort to make ZeroDB not just fast and free, but *honest* — APIs that tell you what actually happened, not what you wanted to hear. If you hit a 400 that you didn't expect, [reach out](mailto:hello@ainative.studio) — we're happy to help you migrate to a real model name. *References: [issue #10547](https://github.com/AINative-Studio/core/issues/10547) in AINative-Studio/core.*
Vector DatabaseZeroDBPlatform Updates

Check your site's AX Score

Free scan, 6 categories, under 60 seconds. See how your site ranks on the agentic web.

Run a free audit →