Resources

Troubleshooting

Solutions to common problems when using Aether.

Authentication errors (401)

Symptom: Every request returns 401 Unauthorized.

Causes and fixes:

  1. No API key reached the client. If you pass the key explicitly, confirm the source you read it from is populated. If you rely on the AETHER_API_KEY environment variable, confirm it's exported in the current shell:

    Bash
    echo $AETHER_API_KEY

    If empty, set it and restart your process:

    Bash
    export AETHER_API_KEY="your-api-key"

  2. Key was revoked. Rotate or re-create the key in the Aether Dashboard, then update your environment.

Rate limit errors (429)

Symptom: Intermittent 429 Too Many Requests, especially under load.

What happened: Your organization exceeded its plan's rate limit.

Fix — add exponential backoff:

import time, random

def with_backoff(fn, max_retries=5):
    for attempt in range(max_retries):
        try:
            return fn()
        except Exception as e:
            if "429" not in str(e):
                raise
            wait = min(2 ** attempt + random.uniform(0, 1), 30)
            time.sleep(wait)
    raise RuntimeError("Max retries exceeded")

If you consistently hit the limit during normal operation, upgrade your plan or contact sales@aetherdb.ai about higher limits.

Plan limit exceeded (402)

Symptom: 402 Plan Limit Exceeded on insert or search calls.

What happened: Your hosted-API tenant hit a quota — document count, storage, or monthly query volume.

Next steps:

  • Check current usage and quota in the Aether Dashboard.
  • Delete documents you no longer need with delete(), or use hard_delete for permanent removal if available on your plan.
  • Upgrade your plan, or contact support if you believe the limit is incorrect.

Search returns no results or irrelevant results

Symptom: search() returns an empty list or low-scoring results.

1. No documents indexed yet. Confirm documents were inserted successfully:

docs = client.list(limit=5)
print(docs.total)  # should be > 0

2. Searching with a different API key. Search only returns documents stored under the same account as the key you're using. If you inserted with one key and search with another, you'll get no results — confirm AETHER_API_KEY matches the account that holds the documents.

3. Score interpretation. Each hit's score is 0-100, higher-is-better. With the default embedding model, low scores usually mean the query doesn't match well; see Tuning retrieval for caveats. Try:

  • Rephrasing the query to be more descriptive
  • Inserting documents with richer, more natural-language content
  • Increasing k to surface weaker matches and evaluate the range of scores

4. Async ingestion still in progress. Documents inserted with insert_async() are not searchable until the job completes. Poll the job status before searching:

import time

job = client.insert_async(file_path="doc.pdf")
while True:
    status = client.get_job(job.job_id)
    if status.status in ("completed", "failed"):
        break
    time.sleep(1)

422 Unprocessable Entity

Symptom: 422 returned when inserting a document.

Causes:

  • Unsupported file type. Aether indexes text formats (plain text, Markdown, JSON, CSV, HTML) and office formats (PDF, DOCX, PPTX, XLSX). Other formats return 422.
  • Embedding dimension mismatch. If you're providing your own embeddings (BYOE), all vectors must share the same dimension. Mixed dimensions return 422.
  • Malformed content. Ensure the request body is valid JSON and all required fields are present.

Async jobs stuck or timing out

Symptom: Jobs inserted with insert_async() never reach a terminal state, or complete with failed.

Checks:

  1. Large files take longer. Big documents are chunked and embedded in the background — allow extra time before assuming a job has stalled.

  2. Check the failure reason. A failed job reports why in its error field:

    Python
    result = client.wait_for_job(job["job_id"])
if result["status"] == "failed":
    print(result.get("error"))

  3. Unsupported content. A job fails if the file isn't a supported format. See Supported file types.

Still stuck?