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:
| Extra field | Appears on |
|---|---|
details | Errors with structured context |
field, max | Validation failures against a numeric cap |
request_id | Correlation identifier for support |
documentation_url | Errors with a canonical explanation |
collection_name | Collection-scoped failures |
existing_regions | A collection that lives in another region |
agents | A collection still referenced by agents |
size_mb, max_size_mb | Response-size failures |
current_etag | Schema compare-and-set conflicts |
retriable | Errors Aetherfy marks as safe to retry |
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.
Every 404 carries a code too. A collection or alias that does not exist is
COLLECTION_NOT_FOUND, answered before anything reaches the storage engine. An
existing collection asked about a point it does not hold answers NOT_FOUND,
with the engine’s own text as the message and nothing else under error.
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 — 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.
| Code | HTTP | Meaning | Retryable |
|---|---|---|---|
MISSING_API_KEY | 401 | No Authorization header, or not a Bearer header | no |
INVALID_API_KEY | 401 | The key does not resolve | no |
ACCOUNT_SUSPENDED | 403 | The account is suspended for billing | no |
NOT_FOUND | 404 | An existing collection does not hold that point (the message is the storage engine’s), or the path is not part of the API | no |
COLLECTION_NOT_FOUND | 404 | No collection or alias of that name in the workspace you addressed. Carries collection_name, as you sent it. Info, the alias list and schema reads addressed through an alias get it too | no |
WORKSPACE_NOT_FOUND | 404 | No such workspace in your account. Carries workspace (by name) or workspace_id (by id). Another account’s workspace id gets the same answer | no |
ALIAS_NOT_FOUND | 404 | An alias batch deletes or renames an alias that does not exist in this workspace. Nothing in the batch was applied | no |
SCHEMA_NOT_DEFINED | 404 | The collection has no stored schema. Both SDKs absorb this one: get_schema returns None / getSchema resolves null rather than raising | no |
METHOD_NOT_ALLOWED | 405 | The method is not supported on that path: a PUT or PATCH on a collection’s own path (create with POST .../collections), or a POST to .../index (create an index with PUT) | no |
ROUTE_RETIRED | 410 | A retired search route (/points/search, /points/recommend, /points/discover, and their /batch and /groups forms). Search with POST .../points/query; the body’s replacement names the route for this collection | no |
WORKSPACE_REQUIRED | 400 | A collection, alias or schema path with no workspace in front (/api/v1/collections/..., /api/v1/aliases, /api/v1/schema/...). Every collection lives in a workspace: use /api/v1/workspaces/{workspace}/... or /api/v1/workspace-ids/{id}/... | no |
WORKSPACE_HAS_NO_REGIONS | 400 | A collection create in a workspace with no regions. Set the workspace’s regions in the dashboard or with afy workspaces regions <name> | no |
INVALID_COLLECTION_NAME | 400 | A collection name that breaks the rule (letters, digits, _, -; up to 100 characters) or begins user_, which is reserved | no |
VALIDATION_ERROR | 400 | A request field failed validation, including a collection name over 100 characters, and an upserted point whose vector is not a plain array of the collection’s dimension (see the example below) | no |
INVALID_FILTER | 400 | A filter has a key that is not recognised: a misspelled clause or condition key at any depth, or two kinds of condition in one object. Carries field (the key’s JSON path in the request body, such as filter.must_not[0].mach), key, and suggestion (the nearest valid key) when one is close. Nothing was applied. See filter validation | no |
INVALID_REQUEST_FIELD | 400 | A request body has a member that is not recognised (a misspelled fitler, limitt, pointz, which the engine would serve as an unfiltered or unbounded request), or two shapes of one request together (points and filter on a delete). Carries field (its JSON path in the body), key and, when one is close, suggestion. On an upsert (PUT .../points) it is any member other than points: update_filter, update_mode, shard_key, ordering and batch are not supported, so a conditional upsert is refused instead of stored as an unconditional one. Seen before points, nothing has been stored; seen after, the points before it have been (an upsert is idempotent, so send them again without it) | no |
INVALID_POINT_ID | 400 | A point id is not an unsigned integer or UUID | no |
TOO_MANY_POINTS | 400 | More than 10 000 points in one upsert | no |
RESERVED_FIELD | 400 | A payload key begins __aetherfy_ | no |
AMBIGUOUS_FILTERED_WRITE | 400 | A filtered keyed set, payload-key delete or vector delete whose filter tests both a key the write changes and the author, or has a shape Aetherfy does not recognise. Nothing was applied. Edit by point ids, or split the request | no |
KEYED_OVERWRITE_NOT_SUPPORTED | 400 | An overwrite carried key, which would replace the whole payload. Nothing was applied. Use set payload with key for a nested change | no |
MALFORMED_JSON | 400 | The body is not valid JSON | no |
SCHEMA_VALIDATION_FAILED | 400 | The payload violates a strictly-enforced schema | no |
INVALID_ENFORCEMENT_MODE | 400 | Not off, warn, or strict | no |
INVALID_SAMPLE_SIZE | 400 | A schema analyze sample_size that is not an integer between 100 and 10 000 | no |
INVALID_SCHEMA | 400 | A schema write whose schema is not a valid payload schema. Nothing was stored | no |
INVALID_REQUEST | 400 | An alias batch with no actions, or an empty list | no |
INVALID_ALIAS_NAME | 400 | An alias name that breaks the naming rule or begins user_. Nothing in the batch was applied | no |
CROSS_SCOPE_ALIAS_NOT_ALLOWED | 400 | An alias action naming an alias or collection with a /: every name in a batch is bare, in the URL’s workspace. Nothing in the batch was applied | no |
AGENT_KEY_WORKSPACE_FORBIDDEN | 403 | An agent’s injected key addressed a workspace it was not granted, by path or in a body. error.workspace names it, or is null when it was addressed by id. The same whether or not the collection, or the workspace, exists. See what an agent’s key reaches | no |
AGENT_ACCESS_LEVEL_INSUFFICIENT | 403 | An agent’s injected key reaches the workspace but holds a lower access level there than the request needs. error.workspace, error.level and error.required_level name them. Nothing was applied | no |
COLLECTION_PROTECTED | 403 | An agent’s injected key tried to delete a protected collection, to remove data from it (points, vectors or payload fields, by id or by filter), or to delete or repoint an alias that points at it. error.collection_name names it. Adding and updating points is not affected. Nothing was applied | no |
PLAN_LIMIT_EXCEEDED | 403 | The plan’s collection cap is reached: error.limit is max_collections, error.allowed the number the plan allows, error.current the collections you hold and error.upgrade_url where to raise the limit (https://app.aetherfy.com/dashboard/settings/billing ). The same code and fields the agents API sends for a plan limit. Nothing was created | no |
AUTH_AGENT_KEY_OUT_OF_SCOPE | 403 | An agent’s injected key called something only a person may do: an account-level route (usage, metrics), or a collection rename. Carries agent_id and required_scope, as on the Aetherfy agents API. Nothing changed | no |
REQUEST_IDLE_TIMEOUT | 408 | 30 s elapsed with no bytes on an upsert | no |
COLLECTION_EXISTS_IN_OTHER_REGION | 409 | The collection already lives elsewhere | no |
COLLECTION_NAME_TAKEN | 409 | A collection rename to a name already used in this workspace. taken_by is collection or alias. (A re-create of a live name is idempotent and returns 200; it never gets this) | no |
ADDRESSED_AN_ALIAS | 409 | A delete or PATCH of a collection, or a schema write or delete, addressed through an alias. Address the collection by its own name. Nothing changed | no |
ALIAS_NAME_IS_A_COLLECTION | 409 | An alias created or renamed onto the name of a collection in the same workspace. Nothing in the batch was applied | no |
ALIAS_NAME_TAKEN | 409 | An alias renamed onto the name of another alias in this workspace. Nothing in the batch was applied | no |
COLLECTION_NAME_IS_AN_ALIAS | 409 | A collection created with the name of an alias in the same workspace. Nothing was created | no |
SCHEMA_VERSION_MISMATCH | 412 | If-Match ETag conflict, or no schema left to match (deleted since you read it); body carries current_etag (null when there is none) and provided_etag. Nothing is changed or created | no |
PAYLOAD_TOO_LARGE | 400 / 413 | Two causes, two statuses: 400 when a single point’s payload exceeds 64 KiB, counted in UTF-8 bytes, 413 when the upsert wire body exceeds the 90 MB ceiling | no |
RESPONSE_TOO_LARGE | 413 | The response would exceed 10 MB | no |
COLLECTION_REGIONS_EMPTY | 422 | No regions resolved for the request | no |
COLLECTION_REGIONS_NOT_IN_SCOPE | 422 | Requested regions are outside the workspace’s regions. Names missing_regions and scope_regions | no |
COLLECTION_SDK_MANAGED | 422 | A rename of the memory SDK’s __threads__ collection, or a rename to a name beginning __threads__. Nothing changed | no |
RATE_LIMIT_EXCEEDED | 429 | The plan’s per-minute request cap is exceeded | yes |
EMERGENCY_RATE_LIMIT | 429 | The rate limiter could not reach its shared store, so each server counted on its own with a lower emergency allowance, and this request exceeded it. Rare and short-lived | yes |
STORAGE_LIMIT_EXCEEDED | 429 | The plan’s storage cap is exceeded — free space first | no |
AUTHENTICATION_ERROR | 500 | Authentication itself failed, rather than the key being rejected. A database that cannot be reached answers SERVICE_UNAVAILABLE instead | yes |
INTERNAL_ERROR | 500 | Unhandled server-side failure | no |
ALIAS_UPDATE_ERROR | 500 | An alias batch failed while being stored. The batch is one transaction: nothing in it was applied | no |
ALIAS_LIST_ERROR | 500 | The aliases could not be listed | no |
PROXY_ERROR | 502 | The proxy could not complete the upstream call | yes |
SERVICE_UNAVAILABLE | 503 | The service is temporarily unable to serve: a service the API depends on could not be reached, or a circuit breaker is open. When it was the database the response carries Retry-After: 5 and the request may already have run part of its work; when a circuit breaker is open it carries Retry-After: 30 and nothing ran | yes |
RESOURCE_BUSY | 503 | Every database connection the service had for the request was in use, so it was refused rather than left hanging; the request may already have run part of its work. Also a collection create that waited about 5 seconds for the account’s collection-create lock (another create of the same account held it), and a restore of a restore point that waited about 5 seconds for the account’s lock (another operation of the same account held it); nothing was done then. Sent with Retry-After: 5 | yes |
WORKSPACE_LOOKUP_UNAVAILABLE | 503 | The workspace could not be looked up. Not a not-found. Nothing was done | yes |
COLLECTION_LOOKUP_UNAVAILABLE | 503 | A collection or alias name could not be resolved right now. Not a not-found. Nothing was done | yes |
PLACEMENT_UNAVAILABLE | 503 | Aetherfy could not look up which regions hold the collection, and the region that answered does not hold it. About region placement only. Nothing was applied | yes |
AGENT_ACCESS_UNAVAILABLE | 503 | Aetherfy could not read which workspaces an agent’s key may use and at what level, or whether a collection is protected, so it refused the request rather than guess. Nothing was applied. A key you create never gets it | yes |
GAUGE_LOCK_UNAVAILABLE | 503 | A collection delete could not take the lock that keeps your storage figure exact. Nothing was deleted | yes |
COLLECTION_DELETE_UNAVAILABLE | 503 | A collection delete could not record the collection and its backup, so it was rolled back as a whole. The collection was not changed | yes |
COLLECTION_BACKUP_NOT_FOUND | 404 | No restore point with that id on the account: its copy was restored already, removed with its workspace, expired, is a day your plan does not reach or that has no daily copy, the id is malformed, or it is another account’s. A restore point is addressed by the id a restore points list gives, never by name | no |
COLLECTION_RESTORE_NOT_FOUND | 404 | No restore with that id on the account. Follow a restore by the restore_id of the 202 that started it, or the restore.id of the running restore in a restore points list; a finished restore is not listed, its collection is on the collections list | no |
COLLECTION_BACKUP_NOT_READY | 409 | The copy taken when the collection was deleted is still being taken (backing_up), so it cannot be restored yet | yes |
COLLECTION_BACKUP_UNAVAILABLE | 409 | The copy taken when the collection was deleted could not be completed after all its attempts. Its data is kept and support can retry it; it cannot be restored until then (unavailable). Contact support | no |
COLLECTION_RESTORE_KEEPS_FAILING | 409 | Restoring this restore point failed three times in the last 24 hours, so it is held until someone looks at why. The failed restores did not count against the month | no |
COLLECTION_NAME_TAKEN_FOR_RESTORE | 409 | A restore under a name a collection or an alias already has in the workspace. collection_name and workspace name them; restore it under another name with as | no |
COLLECTION_RESTORE_IN_PROGRESS | 409 | The restore point is already being restored | yes |
COLLECTION_RESTORE_REGIONS_UNAVAILABLE | 409 | The workspace no longer covers a region the collection lived in. missing_regions names them; add them back to the workspace first | no |
COLLECTION_BEING_RESTORED | 409 | A create of a name a running restore is filling. It is available when the restore finishes | yes |
COLLECTION_BACKUP_EXPIRED | 410 | The deleted collection’s recovery window has passed (your plan’s days from when its copy was ready, or fewer if the plan was lowered); the copy is deleted | no |
GATEWAY_TIMEOUT | 504 | The upstream call timed out | yes |
A VALIDATION_ERROR for a point’s vector
A point’s vector must be a plain array of finite numbers, as many as the collection’s
dimension. An object such as {"": [...]}, an array of the wrong length, or an element
that is not a finite number is refused before the point is stored, with the point and the
dimension in details:
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Point 'p-7' has an invalid vector: it has 3 elements, not 4. A vector of this collection is a plain array of 4 numbers (the single unnamed vector, sent as an array, not as an object).",
"details": { "point_id": "p-7", "expected_dimension": 4 }
}
}Fix the vector and send the upsert again; an upsert is idempotent, so points of the same request that were already stored are simply written again.
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.
| Code | HTTP | Meaning | Retryable |
|---|---|---|---|
BAD_REQUEST | 400 | The engine rejected the request and supplied no code. Read the message | no |
UNAUTHORIZED | 401 | An upstream component refused credentials without naming a code | no |
FORBIDDEN | 403 | An upstream component denied the request without naming a code | no |
CONFLICT | 409 | A conflicting state upstream, unnamed. The specific 409s above are more precise | no |
PRECONDITION_FAILED | 412 | A precondition failed upstream, unnamed — typically an ETag mismatch | no |
RATE_LIMITED | 429 | A 429 from upstream carrying no code of its own | yes |
UPSTREAM_ERROR | 500 / 502 / 503 / 504 | The catch-all: an unmapped upstream status with no code | yes |
RATE_LIMITED is not RATE_LIMIT_EXCEEDED
Both exist, both are 429, and they mean different things. Branch on the code, not the status:
| Code | Who produced it | What it tells you |
|---|---|---|
RATE_LIMIT_EXCEEDED | Aetherfy’s own per-minute rate limiter | You exceeded your plan’s request allowance. Wait the Retry-After seconds; the allowance resets on the next minute bucket |
EMERGENCY_RATE_LIMIT | Aetherfy’s rate limiter, on its emergency fallback | The limiter’s shared store was unreachable and a lower per-server allowance applied. Wait the Retry-After seconds |
RATE_LIMITED | The envelope normaliser, from an upstream 429 | Something upstream of Aetherfy throttled the request without naming a code. Not necessarily your plan allowance |
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
Fourteen Aetherfy codes can succeed on an identical retry — twelve 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.
| Retryable code | HTTP | How to retry against Aetherfy |
|---|---|---|
RATE_LIMIT_EXCEEDED | 429 | Wait the Retry-After seconds, then retry. The header carries the same number as details.reset_in_seconds, the time until the minute’s allowance comes back (at least 1) |
EMERGENCY_RATE_LIMIT | 429 | Wait the Retry-After seconds, then retry. The body carries the same number as details.reset_in_seconds |
PROXY_ERROR | 502 | Retry with backoff |
SERVICE_UNAVAILABLE | 503 | Wait the Retry-After seconds (5 for the database, 30 for an open circuit breaker), then retry with backoff |
RESOURCE_BUSY | 503 | Wait the Retry-After seconds (5), then retry with backoff. It is one of the ambiguous failures in the SDKs’ retry rule below: the request may have run, so only an operation whose repeat gives the same result is retried for you |
GATEWAY_TIMEOUT | 504 | Retry with backoff |
AUTHENTICATION_ERROR | 500 | Authentication itself failed rather than rejecting the key. Retry with backoff |
WORKSPACE_LOOKUP_UNAVAILABLE | 503 | The workspace could not be looked up. Retry with backoff; do not treat it as a missing workspace |
COLLECTION_LOOKUP_UNAVAILABLE | 503 | The collection’s name could not be resolved. Retry with backoff; do not treat it as a missing collection |
PLACEMENT_UNAVAILABLE | 503 | Where the collection lives could not be looked up. Retry with backoff; do not treat it as a missing collection |
AGENT_ACCESS_UNAVAILABLE | 503 | Aetherfy could not read which workspaces an agent’s key may use and at what level, or whether a collection is protected, so it refused the request rather than guess. Retry with backoff |
GAUGE_LOCK_UNAVAILABLE | 503 | A collection delete was refused before anything was deleted. Retry shortly |
COLLECTION_DELETE_UNAVAILABLE | 503 | A collection delete was rolled back as a whole and the collection is unchanged. Retry shortly |
COLLECTION_BACKUP_NOT_READY | 409 | The copy taken when the collection was deleted is still being taken. Retry in a few minutes |
COLLECTION_RESTORE_IN_PROGRESS | 409 | The restore point is already being restored. Follow the restore; do not start another |
COLLECTION_BEING_RESTORED | 409 | A running restore holds the name. Retry when it finishes |
COLLECTION_BACKUP_UNAVAILABLE | 409 | The copy taken when the collection was deleted could not be completed, so it cannot be restored. Its data is kept; contact support, who can retry it. Do not retry the restore |
COLLECTION_RESTORE_KEEPS_FAILING | 409 | Restoring this restore point failed three times in the last 24 hours and it is held until someone looks at why. Contact support; the failed restores did not count against the month |
RATE_LIMITED | 429 | A throttle upstream of Aetherfy, not your plan allowance. Back off with jitter |
UPSTREAM_ERROR | 500 / 502 / 503 / 504 | An unmapped upstream failure. Retry with backoff, and read the message |
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, and it carries no
Retry-After: nothing frees itself while you wait. Delete data or raise the cap. See limits.
How the Aetherfy SDKs map an error to an exception
Both SDKs map by the error’s code, never by its message, and then by status:
| The API answers | The SDK raises |
|---|---|
404 COLLECTION_NOT_FOUND, WORKSPACE_NOT_FOUND, SCHEMA_NOT_DEFINED | CollectionNotFoundError, WorkspaceNotFoundError, SchemaNotFoundError |
404 NOT_FOUND on a point route (the point is missing) | PointNotFoundError |
| Any other 404 | NotFoundError, carrying the code |
| 401, whatever the code | AuthenticationError: the key is missing, wrong or revoked |
403 AGENT_ACCESS_LEVEL_INSUFFICIENT | AccessLevelInsufficientError |
403 COLLECTION_PROTECTED | CollectionProtectedError |
403 AGENT_KEY_WORKSPACE_FORBIDDEN | AgentWorkspaceForbiddenError |
403 AUTH_AGENT_KEY_OUT_OF_SCOPE | AgentKeyOutOfScopeError |
403 PLAN_LIMIT_EXCEEDED, 429 STORAGE_LIMIT_EXCEEDED | QuotaExceededError |
| Any other 403 | PermissionDeniedError: the key is valid, but this is not allowed |
| Any other 429 | RateLimitExceededError |
400 INVALID_FILTER | InvalidFilterError |
400 INVALID_REQUEST_FIELD | InvalidRequestFieldError |
| Any other 400, and 422 whatever the code | ValidationError |
| 502, 503, 504 | ServiceUnavailableError |
409 COLLECTION_EXISTS_IN_OTHER_REGION | CollectionInOtherRegionError |
| Any other 409 | ConflictError |
NotFoundError is the parent of the not-found errors, so one except NotFoundError
(instanceof NotFoundError) handles them all. PermissionDeniedError is the
parent of the four refusals of a valid key above, so one
except PermissionDeniedError (instanceof PermissionDeniedError) handles every
403 except a plan limit. A plan limit is a QuotaExceededError, not a
PermissionDeniedError: the key may do the thing, but the account is at its cap.
InvalidFilterError and InvalidRequestFieldError are children of
ValidationError. Branch on .error_code / .code for the rest.
When an Aetherfy SDK retries a request
One rule, written once and the same in the Python and JavaScript SDKs
(aetherfy_vectors/retry_policy.py, src/retry-policy.ts). Up to 3 retries,
waiting about 1 s, 2 s, then 4 s (each jittered to 50-100%), within a call’s
timeout.
| Failure | Retried for |
|---|---|
Refused before anything ran: 503 WORKSPACE_LOOKUP_UNAVAILABLE, COLLECTION_LOOKUP_UNAVAILABLE, PLACEMENT_UNAVAILABLE; a connection never made (DNS, refused, connect timeout); 429 with a Retry-After | every operation |
| Ambiguous, the request may have run: a read timeout, a reset after sending, any other 5xx | only operations whose repeat gives the same result (below) |
| Any other 4xx | never |
| Operations (Python / JavaScript) | Class |
|---|---|
get_collections, get_collection, collection_exists, get_schema, analyze_schema, search, retrieve, scroll, count, get_usage_stats / getCollections, getCollection, collectionExists, getSchema, analyzeSchema, search, retrieve, scroll, count, getUsageStats | reads: repeatable |
upsert, set_payload, overwrite_payload, delete_payload, create_field_index, set_schema / upsert, setPayload, overwritePayload, deletePayload, createFieldIndex, setSchema | writes keyed by id: repeatable |
create_collection, delete_collection, delete (points), delete_schema, delete_field_index / createCollection, deleteCollection, delete (points), deleteSchema, deleteFieldIndex | once: a repeat after a hidden success reports a false error, so an ambiguous failure is raised after one attempt |
A name that starts create or delete, or an operation that sends a DELETE, is
once unless it is listed above with a reason. There are two: delete_payload
and create_field_index, because repeating an identical request returns at once
with the same result. set_schema is repeatable only because it is sent without
If-Match: a repeat writes the same schema again. A conditional write would get a
false 412 on a repeat after a hidden success, so it would be classed once.
When the answer carries a Retry-After (a RATE_LIMIT_EXCEEDED or EMERGENCY_RATE_LIMIT 429, or a 503),
the SDK waits exactly that long before the retry, with no jitter. It never waits
longer than the cap of 30 seconds (max_delay / maxDelay) and never past the
call’s own deadline: an ask longer than either is raised to you at once, with the
wait on .retry_after / .retryAfter, so your code decides. A 429 without a
Retry-After is never retried. The rate-limit window is a minute, so a reset more
than 30 seconds away reaches you as a RateLimitExceededError carrying the wait.
When the retries run out, the last error is raised (ServiceUnavailableError,
RequestTimeoutError or NetworkError).
Retrying around your own operation
The client already retries under this rule. To retry more around your own
operation, wrap it in the one retry tool both SDKs export from the package root
(retry_with_backoff in Python, retryWithBackoff in JavaScript) and name its
class: REPEATABLE when repeating it gives the same result (a read, a write keyed
by id), ONCE when it does not (a create, a delete). The same failures are
retried as above, and a 4xx never is. The delays are base_delay and max_delay
in seconds in Python, baseDelay and maxDelay in milliseconds in JavaScript;
deadline is an instant after which no retry starts.
from aetherfy_vectors import REPEATABLE, retry_with_backoff
results = retry_with_backoff(
lambda: client.search("articles", query_vector=[0.1, 0.2, 0.3, 0.4], limit=5),
REPEATABLE,
max_retries=3,
base_delay=1.0,
)import { REPEATABLE, retryWithBackoff } from 'aetherfy-vectors';
const results = await retryWithBackoff(
() => client.search('articles', [0.1, 0.2, 0.3, 0.4], { limit: 5 }),
{ retryClass: REPEATABLE, maxRetries: 3, baseDelay: 1000 }
);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.
| Attribute on the base class | Meaning |
|---|---|
.message | Human-readable description |
.request_id | Correlation identifier |
.status_code | HTTP status |
.details | Structured context, when present |
.error_code | The stable code from the envelope |
| Exception | Extra attributes |
|---|---|
AetherfyVectorsException | base class |
AuthenticationError | — (401: the key is missing, wrong or revoked) |
PermissionDeniedError | — (403: the key is valid but this is not allowed; the parent of the four classes below, and what a 403 with a code the SDK does not know arrives as, with that code) |
AccessLevelInsufficientError | .workspace, .level (the agent’s level there), .required_level (what the call needs); each one of the machine values read, read_write, full. AGENT_ACCESS_LEVEL_INSUFFICIENT |
CollectionProtectedError | .collection_name: the collection is protected, so no agent can delete it. COLLECTION_PROTECTED |
AgentKeyOutOfScopeError | .agent_id, .required_scope (None for a route no agent key may call): an agent’s key called an account-level route. AUTH_AGENT_KEY_OUT_OF_SCOPE |
RateLimitExceededError | .retry_after (the Retry-After seconds, None when none was sent) |
ServiceUnavailableError | .retry_after (as above) |
ValidationError | — |
InvalidFilterError | .field (the JSON path of the bad key, such as filter.must[0].range.gtee), .key (the key as sent), .suggestion (the nearest key the grammar has, or None). A child of ValidationError. INVALID_FILTER |
InvalidRequestFieldError | .field, .key, .suggestion, as above, for a top-level member the endpoint does not take. A child of ValidationError. INVALID_REQUEST_FIELD |
NotFoundError | — (the parent of every not-found error below, and what a 404 whose error_code the SDK does not know arrives as, with that code) |
CollectionNotFoundError | — (COLLECTION_NOT_FOUND) |
PointNotFoundError | — (NOT_FOUND on a point route, or POINT_NOT_FOUND) |
WorkspaceNotFoundError | .workspace (the name as sent, None when addressed by id), .workspace_id: no such workspace in your account, WORKSPACE_NOT_FOUND. A typo is never read as an empty result |
RequestTimeoutError | .request_sent (False when the connection was never made) |
NetworkError | .request_sent |
ConflictError | — (any 409 without a more specific class; the backend’s code is in .error_code) |
SchemaValidationError | .errors |
SchemaNotFoundError | — (SCHEMA_NOT_DEFINED; a child of NotFoundError) |
CollectionInOtherRegionError | .existing_regions, .requesting_region |
AgentWorkspaceForbiddenError | .workspace (None when it was addressed by id): an agent’s key addressed a workspace it was not granted, AGENT_KEY_WORKSPACE_FORBIDDEN. A child of PermissionDeniedError |
QuotaExceededError | .limit (the limit’s name, such as max_collections; None for storage, told apart by .error_code STORAGE_LIMIT_EXCEEDED), .allowed (the number your plan allows; False for a feature your plan does not include; None for no cap), .current (what you hold now; None for a yes/no feature), .upgrade_url |
PartialUpsertError | .saved, .total, .failed |
.retry_after is the number of seconds the API asked you to wait, read from the
Retry-After header. The SDK has already waited it and retried where that was
safe, so when you catch one, the wait was longer than the cap or the call’s
deadline: wait .retry_after before you try again.
The SDK already retries what is safe to retry, as described above, so the example below only decides what to do with what is left.
import os
from aetherfy_vectors import (
AetherfyVectorsClient,
AetherfyVectorsException,
AuthenticationError,
PermissionDeniedError,
QuotaExceededError,
RateLimitExceededError,
)
client = AetherfyVectorsClient(api_key=os.environ["AETHERFY_API_KEY"])
try:
results = client.search("articles", query_vector=[0.1, 0.2, 0.3, 0.4], limit=5)
print([hit.id for hit in results])
except AuthenticationError as err:
print("bad key:", err.message)
except PermissionDeniedError as err:
print("not allowed:", err.error_code)
except QuotaExceededError as err:
print("at the cap:", err.limit, err.current, "of", err.allowed, "- raise it at", err.upgrade_url)
except RateLimitExceededError as err:
print("rate limited, wait", err.retry_after, "seconds")
except AetherfyVectorsException as err:
print("failure:", err.error_code, err.status_code)
client.close()Exception classes in the Aetherfy JavaScript SDK
The Aetherfy JavaScript base class is AetherfyVectorsError — note the different
name from Python’s AetherfyVectorsException.
| Member on the base class | Meaning |
|---|---|
.code | The stable code from the envelope |
.requestId | Correlation identifier |
.statusCode | HTTP status |
.details | Structured context, when present |
toJSON() | Serialisable form of the error |
| Exception | Extra members |
|---|---|
AetherfyVectorsError | base class |
AuthenticationError | — (401: the key is missing, wrong or revoked) |
PermissionDeniedError | — (403: the key is valid but this is not allowed; the parent of the four classes below, and the fallback for a 403 with a code the SDK does not know) |
AccessLevelInsufficientError | .workspace, .level, .requiredLevel; each one of the machine values read, read_write, full |
CollectionProtectedError | .collectionName |
AgentKeyOutOfScopeError | .agentId, .requiredScope (null for a route no agent key may call) |
RateLimitExceededError | .retryAfter (the Retry-After seconds, undefined when none was sent) |
ServiceUnavailableError | .retryAfter (as above) |
ValidationError | .field, .violations |
InvalidFilterError | .field (the JSON path of the bad key), .key (the key as sent), .suggestion (the nearest key the grammar has). A child of ValidationError |
InvalidRequestFieldError | .field, .key, .suggestion, for a top-level member the endpoint does not take. A child of ValidationError |
NotFoundError | — (the parent of every not-found error below, and the fallback for a 404 with a code the SDK does not know) |
CollectionNotFoundError | — |
PointNotFoundError | — |
WorkspaceNotFoundError | .workspace (null when addressed by id), .workspaceId: no such workspace in your account |
RequestTimeoutError | — |
NetworkError | .requestSent (false when the connection was never made) |
ConflictError | — |
CollectionInOtherRegionError | — |
AgentWorkspaceForbiddenError | .workspace (null when it was addressed by id): an agent’s key addressed a workspace it was not granted, AGENT_KEY_WORKSPACE_FORBIDDEN. A child of PermissionDeniedError |
QuotaExceededError | .limit, .allowed, .current, .upgradeUrl, with the same meanings as in Python (.allowed is a number, false or null) |
SchemaNotFoundError | — (a child of NotFoundError) |
SchemaValidationError | — |
PartialUpsertError | — |
.retryAfter is the same as Python’s .retry_after: the seconds the API asked
you to wait, read from the Retry-After header, and longer than the SDK would
wait for you.
Two utilities ship alongside them from the Aetherfy package root:
createErrorFromResponse and isAetherfyVectorsError.
import {
AetherfyVectorsClient,
AetherfyVectorsError,
AuthenticationError,
PermissionDeniedError,
QuotaExceededError,
RateLimitExceededError,
isAetherfyVectorsError,
} from 'aetherfy-vectors';
const client = new AetherfyVectorsClient({ apiKey: process.env.AETHERFY_API_KEY });
try {
const results = await client.search('articles', [0.1, 0.2, 0.3, 0.4], { limit: 5 });
console.log(results.map((hit) => hit.id));
} catch (err) {
if (err instanceof AuthenticationError) {
console.log('bad key');
} else if (err instanceof PermissionDeniedError) {
console.log('not allowed:', err.code);
} else if (err instanceof QuotaExceededError) {
console.log('at the cap:', err.limit, err.current, 'of', err.allowed, '- raise it at', err.upgradeUrl);
} else if (err instanceof RateLimitExceededError) {
console.log('rate limited, wait', err.retryAfter, 'seconds');
} else if (isAetherfyVectorsError(err)) {
const e = err as AetherfyVectorsError;
console.log('failure:', e.code, e.statusCode);
} else {
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:
| Declared in | Root export name |
|---|---|
src/exceptions.ts | AuthenticationError |
src/auth.ts | AuthError |
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
| Concept | Python | JavaScript |
|---|---|---|
| Base class | AetherfyVectorsException | AetherfyVectorsError |
| Stable code | .error_code | .code |
| Correlation id | .request_id | .requestId |
| HTTP status | .status_code | .statusCode |
The wait the API asked for (Retry-After, seconds) | .retry_after | .retryAfter |
| A valid key refused (403) | PermissionDeniedError | PermissionDeniedError |
| Type guard | — | isAetherfyVectorsError |
| Conflict class | ConflictError | ConflictError |
The caps and plan limits behind most 4xx codes are on limits; the routes that raise them are on the REST API reference.