Errors and limits

The error envelopeCopy Anchor Link

Every failure — validation, auth, quota, engine — uses the same shape:

{
	"error": {
		"code": "QUOTA_EXCEEDED",
		"message": "Monthly searches quota exhausted (500000/500000 for 2026-10)",
		"request_id": "req_3c5e7a9b1d3f5a7c9e1b3d5f",
		"details": {
			"metric": "searches",
			"limit": 500000,
			"used": 500000,
			"period": "2026-10",
			"resetsAt": "2026-11-01T00:00:00.000Z"
		}
	}
}

code is a stable identifier you can branch on; message is for humans and may change; request_id also comes back in the x-request-id header. details is present only when there is something useful to say.

curl -sS -i "$AAC_API/indexes/documentation/search?q=pricing&num_typos=9" \
  -H "Authorization: Bearer $AAC_KEY"

{
	"error": {
		"code": "VALIDATION_ERROR",
		"message": "Request payload is invalid",
		"request_id": "req_7d9f1b3c5e7a9b1d3f5c7a9b",
		"details": {
			"issues": [
				{
					"code": "too_big",
					"path": ["num_typos"],
					"message": "Number must be less than or equal to 3"
				}
			]
		}
	}
}

Codes by statusCopy Anchor Link

400Copy Anchor Link

401Copy Anchor Link

402Copy Anchor Link

403Copy Anchor Link

An acl claim in a search request is ignored — not rejected — when the key has an allowedOrigins list or the request carries an Origin header: a browser-exposed credential cannot choose whose documents it sees. Such searches see only documents without an ACL.

404Copy Anchor Link

409Copy Anchor Link

413Copy Anchor Link

422Copy Anchor Link

429Copy Anchor Link

5xxCopy Anchor Link

Engine and provider errors are mapped to this public contract before they leave the API, and internal names never appear in a response: an engine 404 becomes INDEX_NOT_FOUND, 409 becomes INDEX_ALREADY_EXISTS, 400/422 become INVALID_QUERY (an unknown field in filter_by/sort_by/facet_by/query_by/group_by becomes FIELD_NOT_IN_SCHEMA), timeouts become SEARCH_TIMEOUT, and everything else (including a missing engine configuration) becomes SEARCH_UNAVAILABLE. Other aliases: AI_PROVIDER_ERROR → AI_UNAVAILABLE, ENGINE_FEATURE_UNSUPPORTED → FEATURE_UNSUPPORTED, INDEX_HAS_NO_EMBEDDING_FIELD → INDEX_NOT_VECTOR_ENABLED. The raw engine message is logged server-side and correlated by request_id; quote that id to support.

Rate limitsCopy Anchor Link

Requests are limited per API key in a sliding window:

Every authenticated response carries x-ratelimit-limit, x-ratelimit-remaining and x-ratelimit-reset (Unix seconds), including successful ones, so a client can pace itself. Exceeding the limit is a 429 with a reset time:

curl -sS -i "$AAC_API/indexes/documentation/search?q=pricing" \
  -H "Authorization: Bearer $AAC_KEY"

{
	"error": {
		"code": "RATE_LIMITED",
		"message": "Rate limit exceeded",
		"request_id": "req_9b1d3f5a7c9e1b3d5f7a9c1e",
		"details": { "limit": 600, "reset_at": "2026-10-23T10:42:00.000Z" }
	}
}

The limiter is in-process by default and shared through Redis when REDIS_URL is set. Behind several instances without Redis, each instance enforces its own 600 — plan for that when sizing.

RATE_LIMITED and QUOTA_EXCEEDED are both 429 but mean different things: the first clears in seconds, the second only at the start of the next billing period or when the plan is upgraded. Read error.code, never the status alone.

Plan quotasCopy Anchor Link

Metered metrics are searches, documents, ai_tokens and reindex. Allowances per billing period, from the billing catalog:

Overage prices per block:

Free has no overage prices at all: reaching a limit returns 429 QUOTA_EXCEEDED and nothing is charged. Paid plans meter overage against the prepaid wallet.

Features gated by plan: Free includes keyword search, synonyms, stopwords, aiAnswer (RAG, within the 10,000 AI-token allowance) and scheduledSync, but not vectorSearch, hybridSearch, curations, grouping, geoSearch, multiSearch, reindex, exportDocuments, customSort or queryAnalytics. Using a gated feature returns 402 PAYMENT_REQUIRED from the metering layer; a plan that lacks the feature fails the request rather than silently degrading it. Missing API key scope still returns 403 FORBIDDEN.

Wallet and overageCopy Anchor Link

1. Usage is counted per period (YYYY-MM), resetting at 00:00 UTC on the first of the month.
2. Up to the included allowance, a call costs nothing.
3. Beyond it, each block is debited from the wallet: searches in 1,000-unit blocks, documents/ai_tokens likewise, reindex per run.
4. With a zero balance the call fails with 402 PAYMENT_REQUIRED and top-up instructions in the message; a plan feature that needs payment fails the same way.
5. Top-ups are prepaid credit packs — $10, $50, $200 — bought through the payment provider and reconciled into the ledger.

Read the state before it bites:

curl -sS "$AAC_API/billing/wallet" -H "Authorization: Bearer $AAC_KEY"

{
	"wallet": { "balanceCents": 4200, "currency": "USD" },
	"plan": "pro",
	"period": "2026-10",
	"resets_at": "2026-11-01T00:00:00.000Z",
	"transactions": [
		{
			"id": "txn_01HZYA",
			"type": "credit",
			"amount_cents": 5000,
			"balance_after_cents": 5000,
			"description": "Top-up credits_50",
			"metric": null,
			"created_at": "2026-10-02T09:12:00.000Z"
		},
		{
			"id": "txn_01HZYB",
			"type": "debit",
			"amount_cents": -800,
			"balance_after_cents": 4200,
			"description": "search overage: 16 blocks",
			"metric": "searches",
			"created_at": "2026-10-21T18:03:11.000Z"
		}
	],
	"request_id": "req_4f6a8c0e2b4d6f8a0c2e4b6d"
}

curl -sS "$AAC_API/billing/usage" -H "Authorization: Bearer $AAC_KEY"

{
	"usage": {
		"plan": "pro",
		"planName": "Pro",
		"period": "2026-10",
		"resetsAt": "2026-11-01T00:00:00.000Z",
		"searches": { "used": 500000, "limit": 500000 },
		"documents": { "used": 51204, "limit": 50000 },
		"aiTokens": { "used": 24800, "limit": 100000 },
		"indexes": { "used": 3, "limit": 10 },
		"apiKeys": { "used": 2, "limit": 10 },
		"connectors": { "used": 1, "limit": 10 },
		"wallet": { "balanceCents": 4200, "currency": "USD" }
	},
	"request_id": "req_2b4d6f8a0c2e4b6d8f0a2c4e"
}

documents is counted from the document mirror, not from a counter, so it reflects what is actually in the index. wallet is null when the tenant has never had a credit.

Operational guidanceCopy Anchor Link

• Back off on 429 only. Retry-After is not sent; use details.reset_at or x-ratelimit-reset.
• Do not retry 4xx other than 429. A 403 will not become a 200 by repeating it; a 422 payload needs fixing.
• Retry 5xx with jitter. The SDKs retry twice by default with exponential backoff.
• Watch x-aac-quota-remaining. Failing at the quota boundary is avoidable if you alert at 10% remaining.
• Alert on zero-result rate, not on 200s. A search that returns nothing is a success by HTTP and a failure by product.