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 Aetherfy can return, with its HTTP status and whether retrying the identical request can succeed.

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

Only five Aetherfy codes can succeed on an identical retry. Everything else is a statement about the request or the account, and repeating it verbatim produces the same answer.

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 429, 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 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 tier limits behind most 4xx codes are on limits; the routes that raise them are on the REST API reference.