Ingest failures

Ingestion is decoupled from indexing: a write enters SearchIngestBuffer, a worker picks it up and applies it to the live index. A "failure" can mean a 4xx at the API edge, a 4xx at the worker, or a stuck queue. Each has a different fix.

Symptom

Decision tree

Did the API return 2xx?
  ├─ no  → fix the request body; see "Validation errors" below
  └─ yes → check buffer queue depth
            ├─ depth 0 → worker has processed it; check schema match
            └─ depth > 0 → wait; see "Queue lag" below

Check 1: API response

A successful enqueue returns { "enqueued": <n>, "errors": [] }. A partial-success returns the per-document errors:

{
	"enqueued": 998,
	"errors": [
		{
			"external_id": "product-123",
			"error": "validation_failed",
			"message": "Field 'price' expected float, got string"
		},
		{
			"external_id": "product-456",
			"error": "missing_field",
			"message": "Required field 'title' is missing"
		}
	]
}

Fix each row according to its error code. The other 998 are already on their way to the index.

Common validation errors

Check 2: buffer queue depth

If the API said enqueued: N but documents are not visible after 2 minutes, check the queue:

curl -X GET https://app.aacsearch.com/api/v1/projects/<projectId>/usage \
  -H "Authorization: Bearer aa_admin_..."

Response includes a bufferDepth for the org. Healthy depth is < 1000 most of the time. Sustained depth > 50,000 indicates the worker is throttled.

Check 3: schema mismatch

A document can pass edge validation but fail at the worker if a field type changed since the index schema was set. Worker rejections are surfaced in the dashboard:

Search → Indexes → the index → "Recent ingest errors" tab.

Common causes:

• The connector started sending a new field that has no facet/type definition.
• A field changed from string to string[] upstream.
• A nested object got flattened differently than the schema expects.

Update the schema (admin API → PATCH /v1/indexes/<id>) and re-push the affected documents.

Check 4: reindex in progress

During a full reindex, the live alias is swapped at the end. While reindex is running, new writes are written to both the old and new collection. Writes are not lost, but you may see a temporary lag.

Check Search → Indexes → status. If status is reindexing, wait for it to complete. See reindexing and zero-downtime for the full lifecycle.

Check 5: connector specifics

If you are using a connector (PrestaShop, Bitrix, Postgres-sync), check the connector's last sync job:

curl -X GET https://app.aacsearch.com/api/v1/projects/<projectId>/sync-jobs \
  -H "Authorization: Bearer aa_admin_..."

Each row has a status: pending, running, completed, failed. Failed jobs include the underlying error and a sample document that failed.

Pressure: worker throttled

If bufferDepth is climbing into the hundreds of thousands and not draining, one of these is happening:

Fix matrix

Diagnostics packet

Related

• Connector API lifecycle — endpoint reference
• Connector sync — connector-specific issues
• Reindexing and zero-downtime
• Auth errors — for 401/403 on ingest endpoints