Errors in the Aetherfy vector database

The Aetherfy error envelope

Every error the Aetherfy vector API authors is returned in one shape:

{
  "error": {
    "code": "STABLE_CODE",
    "message": "human readable description"
  }
}

code is the stable, machine-readable identifier — branch on it, never on the message text, which is written for humans and may be reworded. Alongside the two required fields, an Aetherfy error may carry extras that depend on the site that raised it:

The Aetherfy error envelope is universal

Every path authors the envelope, including the storage-engine pass-through routes. Those routes proxy Qdrant, whose native failure body is shaped {"status": {"error": "..."}, "time": 0.001} — Aetherfy normalises it on the way out rather than relaying it, so error.code is always present and a generic handler can rely on it.

Earlier versions of these docs described POST /api/v1/collections/{name}/points/retrieve as an exception that relayed the engine body verbatim. That is no longer true. If you wrote a handler tolerating a missing error.code on that route, the tolerance is now dead code — harmless, but you can drop it.

Error codes in the Aetherfy vector API

Every code the Aetherfy vector API returns, with its HTTP status and whether retrying the identical request can succeed. Aetherfy’s agent and platform surfaces have codes of their own — PLAN_LIMIT_EXCEEDED, RUNTIME_IMMUTABLE, the AGENT_* and WORKSPACE_* families, SOFT_CAP_EXCEEDED, DUNNING_FROZEN — which are documented on the pages that raise them: /platform/limits, /platform/billing, /platform/workspaces and /agents/managing. Every Aetherfy code from every surface is also published as machine-readable data at errors.json, the catalogue described on Using AI with Aetherfy.

How recently counts as “in use”

COLLECTION_IN_USE is the one code above whose meaning depends on a clock, so the rule is worth stating exactly: an agent blocks a delete for 35 days after the last time it read or wrote the collection. Older than that and it no longer blocks anything.

There is nothing to configure and nothing to declare. Aetherfy records which collections each agent actually reads and writes, so a collection your agent code created at runtime is protected exactly like one it has used since its first deploy. The 409 body’s agents array names the agents currently blocking the delete.

Two consequences worth knowing before you script against it:

• An agent that runs monthly still blocks its collection. That is what the 35 days is for — the longest month, plus a few days of slack for a paused agent or a run that slipped. A scheduled task that fires on the 1st is inside the window on the 31st.
• A brand-new agent blocks nothing yet. Until it has actually opened the collection, there is nothing to observe, and the delete succeeds. “No agent has touched this collection” and “no agent uses this collection” are different statements, and only the first one is ever checked.

Aetherfy’s fallback error codes

The codes above are authored deliberately: something in Aetherfy decided that exact failure and named it. The codes below are different in kind. Aetherfy proxies a storage engine and authors the error envelope on the way out — when the upstream body carries a usable code, that code is preserved; when it does not, Aetherfy synthesises one from the HTTP status.

Seeing one of these means the upstream failed without naming its own reason, so the message carries more signal than the code. Treat them as “something upstream went wrong, here is roughly what kind” rather than as specific diagnoses.

RATE_LIMITED is not RATE_LIMIT_EXCEEDED

Both exist, both are 429, and they mean different things. Branch on the code, not the status:

A retry loop keyed on status === 429 will treat these identically, which is usually fine — both want backoff. A dashboard or alert that reports “you hit your rate limit” should key on RATE_LIMIT_EXCEEDED specifically, or it will misattribute an upstream throttle to the customer’s plan.

Which Aetherfy errors are worth retrying

Seven Aetherfy codes can succeed on an identical retry — five that Aetherfy authors deliberately, and two that the envelope normaliser synthesises from an upstream failure. Every other code on this page is a statement about the request or the account, and repeating it verbatim produces the same answer.

The two normaliser codes are worth handling separately from their authored twins: they carry no diagnosis of their own, so a retry that keeps failing on UPSTREAM_ERROR or RATE_LIMITED needs its message read rather than its backoff lengthened.

STORAGE_LIMIT_EXCEEDED is a 429 but is not retryable: nothing frees itself while you wait. Delete data or raise the cap. See limits.

Exception classes in the Aetherfy Python SDK

The Aetherfy Python SDK maps API errors onto typed exceptions. The base class is AetherfyVectorsException; catch it to catch everything the SDK authors.

.retry_after on RateLimitExceededError is an attribute of the class, not a value Aetherfy supplies: Aetherfy sends no Retry-After header on a vector-API 429, and this SDK only ever calls the vector API, so there is nothing to populate it from. Do not branch on it — back off on your own schedule.

The helper is_retryable_error(error) lives in aetherfy_vectors.exceptions and answers the retry question for you.

import os
import time
 
from aetherfy_vectors import (
    AetherfyVectorsClient,
    AetherfyVectorsException,
    AuthenticationError,
    QuotaExceededError,
    RateLimitExceededError,
)
from aetherfy_vectors.exceptions import is_retryable_error
 
client = AetherfyVectorsClient(api_key=os.environ["AETHERFY_API_KEY"])
 
for attempt in range(3):
    try:
        results = client.search("articles", query_vector=[0.1, 0.2, 0.3, 0.4], limit=5)
        print([hit.id for hit in results])
        break
    except AuthenticationError as err:
        print("bad key, not retrying:", err.message)
        break
    except QuotaExceededError as err:
        print("quota:", err.quota_type, err.current, err.limit)
        break
    except RateLimitExceededError as err:
        print("rate limited, request_id:", err.request_id)
        time.sleep(2 ** attempt)
    except AetherfyVectorsException as err:
        if not is_retryable_error(err):
            print("permanent failure:", err.error_code, err.status_code)
            break
        time.sleep(2 ** attempt)
 
client.close()

Exception classes in the Aetherfy JavaScript SDK

The Aetherfy JavaScript base class is AetherfyVectorsError — note the different name from Python’s AetherfyVectorsException.

.retryAfter on the Aetherfy JavaScript RateLimitExceededError is the same story as Python’s .retry_after: the member exists on the class, but because Aetherfy sends no Retry-After header on a vector-API 429 there is nothing to populate it from. Do not branch on it — back off on your own schedule.

Three utilities ship alongside them from the Aetherfy package root: createErrorFromResponse, isAetherfyVectorsError, and isRetryableError.

import {
  AetherfyVectorsClient,
  AetherfyVectorsError,
  AuthenticationError,
  QuotaExceededError,
  RateLimitExceededError,
  isAetherfyVectorsError,
  isRetryableError,
} from 'aetherfy-vectors';
 
const client = new AetherfyVectorsClient({ apiKey: process.env.AETHERFY_API_KEY });
const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
 
for (let attempt = 0; attempt < 3; attempt += 1) {
  try {
    const results = await client.search('articles', [0.1, 0.2, 0.3, 0.4], { limit: 5 });
    console.log(results.map((hit) => hit.id));
    break;
  } catch (err) {
    if (err instanceof AuthenticationError) {
      console.log('bad key, not retrying');
      break;
    }
    if (err instanceof QuotaExceededError) {
      console.log('quota exceeded');
      break;
    }
    if (err instanceof RateLimitExceededError) {
      console.log('rate limited, requestId:', err.requestId);
      await sleep(2 ** attempt * 1000);
      continue;
    }
    if (isAetherfyVectorsError(err)) {
      if (!isRetryableError(err)) {
        const e = err as AetherfyVectorsError;
        console.log('permanent failure:', e.code, e.statusCode);
        break;
      }
      await sleep(2 ** attempt * 1000);
      continue;
    }
    throw err;
  }
}
 
client.dispose();

The duplicate AuthenticationError in the Aetherfy JavaScript SDK

The Aetherfy JavaScript package defines two classes named AuthenticationError, in two modules. To keep the package root unambiguous, the one declared in src/auth.ts is re-exported under a different name:

So AuthenticationError imported from the Aetherfy package root is the transport-level error raised when the API rejects a key, and AuthError is the key-management one. An instanceof check against the wrong class silently never matches, so import the name that corresponds to the layer you are catching.

Mapping Aetherfy error names across the two SDKs

The caps and plan limits behind most 4xx codes are on limits; the routes that raise them are on the REST API reference.