Skip to Content
Raw

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 fieldAppears on
detailsErrors with structured context
field, maxValidation failures against a numeric cap
request_idCorrelation identifier for support
documentation_urlErrors with a canonical explanation
collection_nameCollection-scoped failures
existing_regionsA collection that lives in another region
agentsA collection still referenced by agents
size_mb, max_size_mbResponse-size failures
current_etagSchema compare-and-set conflicts
retriableErrors 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.

CodeHTTPMeaningRetryable
MISSING_API_KEY401No Authorization header, or not a Bearer headerno
INVALID_API_KEY401The key does not resolveno
ACCOUNT_SUSPENDED403The account is suspended for billingno
NOT_FOUND404An existing collection does not hold that point (the message is the storage engine’s), or the path is not part of the APIno
COLLECTION_NOT_FOUND404No 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 toono
WORKSPACE_NOT_FOUND404No such workspace in your account. Carries workspace (by name) or workspace_id (by id). Another account’s workspace id gets the same answerno
ALIAS_NOT_FOUND404An alias batch deletes or renames an alias that does not exist in this workspace. Nothing in the batch was appliedno
SCHEMA_NOT_DEFINED404The collection has no stored schema. Both SDKs absorb this one: get_schema returns None / getSchema resolves null rather than raisingno
METHOD_NOT_ALLOWED405The 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_RETIRED410A 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 collectionno
WORKSPACE_REQUIRED400A 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_REGIONS400A 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_NAME400A collection name that breaks the rule (letters, digits, _, -; up to 100 characters) or begins user_, which is reservedno
VALIDATION_ERROR400A 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_FILTER400A 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 validationno
INVALID_REQUEST_FIELD400A 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_ID400A point id is not an unsigned integer or UUIDno
TOO_MANY_POINTS400More than 10 000 points in one upsertno
RESERVED_FIELD400A payload key begins __aetherfy_no
AMBIGUOUS_FILTERED_WRITE400A 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 requestno
KEYED_OVERWRITE_NOT_SUPPORTED400An overwrite carried key, which would replace the whole payload. Nothing was applied. Use set payload with key for a nested changeno
MALFORMED_JSON400The body is not valid JSONno
SCHEMA_VALIDATION_FAILED400The payload violates a strictly-enforced schemano
INVALID_ENFORCEMENT_MODE400Not off, warn, or strictno
INVALID_SAMPLE_SIZE400A schema analyze sample_size that is not an integer between 100 and 10 000no
INVALID_SCHEMA400A schema write whose schema is not a valid payload schema. Nothing was storedno
INVALID_REQUEST400An alias batch with no actions, or an empty listno
INVALID_ALIAS_NAME400An alias name that breaks the naming rule or begins user_. Nothing in the batch was appliedno
CROSS_SCOPE_ALIAS_NOT_ALLOWED400An 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 appliedno
AGENT_KEY_WORKSPACE_FORBIDDEN403An 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 reachesno
AGENT_ACCESS_LEVEL_INSUFFICIENT403An 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 appliedno
COLLECTION_PROTECTED403An 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 appliedno
PLAN_LIMIT_EXCEEDED403The 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 createdno
AUTH_AGENT_KEY_OUT_OF_SCOPE403An 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 changedno
REQUEST_IDLE_TIMEOUT40830 s elapsed with no bytes on an upsertno
COLLECTION_EXISTS_IN_OTHER_REGION409The collection already lives elsewhereno
COLLECTION_NAME_TAKEN409A 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_ALIAS409A delete or PATCH of a collection, or a schema write or delete, addressed through an alias. Address the collection by its own name. Nothing changedno
ALIAS_NAME_IS_A_COLLECTION409An alias created or renamed onto the name of a collection in the same workspace. Nothing in the batch was appliedno
ALIAS_NAME_TAKEN409An alias renamed onto the name of another alias in this workspace. Nothing in the batch was appliedno
COLLECTION_NAME_IS_AN_ALIAS409A collection created with the name of an alias in the same workspace. Nothing was createdno
SCHEMA_VERSION_MISMATCH412If-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 createdno
PAYLOAD_TOO_LARGE400 / 413Two 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 ceilingno
RESPONSE_TOO_LARGE413The response would exceed 10 MBno
COLLECTION_REGIONS_EMPTY422No regions resolved for the requestno
COLLECTION_REGIONS_NOT_IN_SCOPE422Requested regions are outside the workspace’s regions. Names missing_regions and scope_regionsno
COLLECTION_SDK_MANAGED422A rename of the memory SDK’s __threads__ collection, or a rename to a name beginning __threads__. Nothing changedno
RATE_LIMIT_EXCEEDED429The plan’s per-minute request cap is exceededyes
EMERGENCY_RATE_LIMIT429The 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-livedyes
STORAGE_LIMIT_EXCEEDED429The plan’s storage cap is exceeded — free space firstno
AUTHENTICATION_ERROR500Authentication itself failed, rather than the key being rejected. A database that cannot be reached answers SERVICE_UNAVAILABLE insteadyes
INTERNAL_ERROR500Unhandled server-side failureno
ALIAS_UPDATE_ERROR500An alias batch failed while being stored. The batch is one transaction: nothing in it was appliedno
ALIAS_LIST_ERROR500The aliases could not be listedno
PROXY_ERROR502The proxy could not complete the upstream callyes
SERVICE_UNAVAILABLE503The 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 ranyes
RESOURCE_BUSY503Every 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: 5yes
WORKSPACE_LOOKUP_UNAVAILABLE503The workspace could not be looked up. Not a not-found. Nothing was doneyes
COLLECTION_LOOKUP_UNAVAILABLE503A collection or alias name could not be resolved right now. Not a not-found. Nothing was doneyes
PLACEMENT_UNAVAILABLE503Aetherfy could not look up which regions hold the collection, and the region that answered does not hold it. About region placement only. Nothing was appliedyes
AGENT_ACCESS_UNAVAILABLE503Aetherfy 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 ityes
GAUGE_LOCK_UNAVAILABLE503A collection delete could not take the lock that keeps your storage figure exact. Nothing was deletedyes
COLLECTION_DELETE_UNAVAILABLE503A collection delete could not record the collection and its backup, so it was rolled back as a whole. The collection was not changedyes
COLLECTION_BACKUP_NOT_FOUND404No 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 nameno
COLLECTION_RESTORE_NOT_FOUND404No 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 listno
COLLECTION_BACKUP_NOT_READY409The copy taken when the collection was deleted is still being taken (backing_up), so it cannot be restored yetyes
COLLECTION_BACKUP_UNAVAILABLE409The 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 supportno
COLLECTION_RESTORE_KEEPS_FAILING409Restoring 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 monthno
COLLECTION_NAME_TAKEN_FOR_RESTORE409A 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 asno
COLLECTION_RESTORE_IN_PROGRESS409The restore point is already being restoredyes
COLLECTION_RESTORE_REGIONS_UNAVAILABLE409The workspace no longer covers a region the collection lived in. missing_regions names them; add them back to the workspace firstno
COLLECTION_BEING_RESTORED409A create of a name a running restore is filling. It is available when the restore finishesyes
COLLECTION_BACKUP_EXPIRED410The 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 deletedno
GATEWAY_TIMEOUT504The upstream call timed outyes

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.

CodeHTTPMeaningRetryable
BAD_REQUEST400The engine rejected the request and supplied no code. Read the messageno
UNAUTHORIZED401An upstream component refused credentials without naming a codeno
FORBIDDEN403An upstream component denied the request without naming a codeno
CONFLICT409A conflicting state upstream, unnamed. The specific 409s above are more preciseno
PRECONDITION_FAILED412A precondition failed upstream, unnamed — typically an ETag mismatchno
RATE_LIMITED429A 429 from upstream carrying no code of its ownyes
UPSTREAM_ERROR500 / 502 / 503 / 504The catch-all: an unmapped upstream status with no codeyes

RATE_LIMITED is not RATE_LIMIT_EXCEEDED

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

CodeWho produced itWhat it tells you
RATE_LIMIT_EXCEEDEDAetherfy’s own per-minute rate limiterYou exceeded your plan’s request allowance. Wait the Retry-After seconds; the allowance resets on the next minute bucket
EMERGENCY_RATE_LIMITAetherfy’s rate limiter, on its emergency fallbackThe limiter’s shared store was unreachable and a lower per-server allowance applied. Wait the Retry-After seconds
RATE_LIMITEDThe envelope normaliser, from an upstream 429Something 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 codeHTTPHow to retry against Aetherfy
RATE_LIMIT_EXCEEDED429Wait 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_LIMIT429Wait the Retry-After seconds, then retry. The body carries the same number as details.reset_in_seconds
PROXY_ERROR502Retry with backoff
SERVICE_UNAVAILABLE503Wait the Retry-After seconds (5 for the database, 30 for an open circuit breaker), then retry with backoff
RESOURCE_BUSY503Wait 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_TIMEOUT504Retry with backoff
AUTHENTICATION_ERROR500Authentication itself failed rather than rejecting the key. Retry with backoff
WORKSPACE_LOOKUP_UNAVAILABLE503The workspace could not be looked up. Retry with backoff; do not treat it as a missing workspace
COLLECTION_LOOKUP_UNAVAILABLE503The collection’s name could not be resolved. Retry with backoff; do not treat it as a missing collection
PLACEMENT_UNAVAILABLE503Where the collection lives could not be looked up. Retry with backoff; do not treat it as a missing collection
AGENT_ACCESS_UNAVAILABLE503Aetherfy 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_UNAVAILABLE503A collection delete was refused before anything was deleted. Retry shortly
COLLECTION_DELETE_UNAVAILABLE503A collection delete was rolled back as a whole and the collection is unchanged. Retry shortly
COLLECTION_BACKUP_NOT_READY409The copy taken when the collection was deleted is still being taken. Retry in a few minutes
COLLECTION_RESTORE_IN_PROGRESS409The restore point is already being restored. Follow the restore; do not start another
COLLECTION_BEING_RESTORED409A running restore holds the name. Retry when it finishes
COLLECTION_BACKUP_UNAVAILABLE409The 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_FAILING409Restoring 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_LIMITED429A throttle upstream of Aetherfy, not your plan allowance. Back off with jitter
UPSTREAM_ERROR500 / 502 / 503 / 504An 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 answersThe SDK raises
404 COLLECTION_NOT_FOUND, WORKSPACE_NOT_FOUND, SCHEMA_NOT_DEFINEDCollectionNotFoundError, WorkspaceNotFoundError, SchemaNotFoundError
404 NOT_FOUND on a point route (the point is missing)PointNotFoundError
Any other 404NotFoundError, carrying the code
401, whatever the codeAuthenticationError: the key is missing, wrong or revoked
403 AGENT_ACCESS_LEVEL_INSUFFICIENTAccessLevelInsufficientError
403 COLLECTION_PROTECTEDCollectionProtectedError
403 AGENT_KEY_WORKSPACE_FORBIDDENAgentWorkspaceForbiddenError
403 AUTH_AGENT_KEY_OUT_OF_SCOPEAgentKeyOutOfScopeError
403 PLAN_LIMIT_EXCEEDED, 429 STORAGE_LIMIT_EXCEEDEDQuotaExceededError
Any other 403PermissionDeniedError: the key is valid, but this is not allowed
Any other 429RateLimitExceededError
400 INVALID_FILTERInvalidFilterError
400 INVALID_REQUEST_FIELDInvalidRequestFieldError
Any other 400, and 422 whatever the codeValidationError
502, 503, 504ServiceUnavailableError
409 COLLECTION_EXISTS_IN_OTHER_REGIONCollectionInOtherRegionError
Any other 409ConflictError

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.

FailureRetried 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-Afterevery operation
Ambiguous, the request may have run: a read timeout, a reset after sending, any other 5xxonly operations whose repeat gives the same result (below)
Any other 4xxnever
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, getUsageStatsreads: repeatable
upsert, set_payload, overwrite_payload, delete_payload, create_field_index, set_schema / upsert, setPayload, overwritePayload, deletePayload, createFieldIndex, setSchemawrites keyed by id: repeatable
create_collection, delete_collection, delete (points), delete_schema, delete_field_index / createCollection, deleteCollection, delete (points), deleteSchema, deleteFieldIndexonce: 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 classMeaning
.messageHuman-readable description
.request_idCorrelation identifier
.status_codeHTTP status
.detailsStructured context, when present
.error_codeThe stable code from the envelope
ExceptionExtra attributes
AetherfyVectorsExceptionbase 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 classMeaning
.codeThe stable code from the envelope
.requestIdCorrelation identifier
.statusCodeHTTP status
.detailsStructured context, when present
toJSON()Serialisable form of the error
ExceptionExtra members
AetherfyVectorsErrorbase 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 inRoot export name
src/exceptions.tsAuthenticationError
src/auth.tsAuthError

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

ConceptPythonJavaScript
Base classAetherfyVectorsExceptionAetherfyVectorsError
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)PermissionDeniedErrorPermissionDeniedError
Type guard—isAetherfyVectorsError
Conflict classConflictErrorConflictError

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

Last updated on