Ошибки и лимиты

Конверт ошибокCopy Anchor Link

Любая ошибка — валидация, аутентификация, квота, движок — приходит в одном формате:

{
	"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 — стабильный идентификатор, по нему можно ветвиться; message предназначен людям и может меняться; request_id дублируется в заголовке x-request-id. details присутствует только тогда, когда есть что сообщить.

curl -sS -i "$AAC_API/indexes/documentation/search?q=тарифы&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"
				}
			]
		}
	}
}

Коды по статусамCopy Anchor Link

400Copy Anchor Link

401Copy Anchor Link

402Copy Anchor Link

403Copy Anchor Link

Утверждение acl в запросе поиска игнорируется (а не отклоняется), если у ключа есть список allowedOrigins или запрос пришёл с заголовком Origin: ключ, видимый в браузере, не может выбирать, чьи документы он видит. Такой поиск видит только документы без ACL.

404Copy Anchor Link

409Copy Anchor Link

413Copy Anchor Link

422Copy Anchor Link

429Copy Anchor Link

5xxCopy Anchor Link

Ошибки движка и провайдеров приводятся к этому публичному контракту до выхода из API, внутренние имена в ответе не появляются: 404 движка становится INDEX_NOT_FOUND, 409 — INDEX_ALREADY_EXISTS, 400/422 — INVALID_QUERY (неизвестное поле в filter_by/sort_by/facet_by/query_by/group_by — FIELD_NOT_IN_SCHEMA), таймауты — SEARCH_TIMEOUT, всё остальное (включая отсутствие конфигурации движка) — SEARCH_UNAVAILABLE. Другие алиасы: AI_PROVIDER_ERROR → AI_UNAVAILABLE, ENGINE_FEATURE_UNSUPPORTED → FEATURE_UNSUPPORTED, INDEX_HAS_NO_EMBEDDING_FIELD → INDEX_NOT_VECTOR_ENABLED. Исходное сообщение движка пишется в лог на сервере и связывается через request_id; назовите этот id в поддержке.

Лимиты запросовCopy Anchor Link

Запросы ограничиваются на API-ключ в скользящем окне:

Каждый аутентифицированный ответ несёт x-ratelimit-limit, x-ratelimit-remaining и x-ratelimit-reset (Unix-время в секундах), включая успешные, — так клиент может сам выдерживать темп. Превышение — 429 с временем сброса:

curl -sS -i "$AAC_API/indexes/documentation/search?q=тарифы" \
  -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" }
	}
}

По умолчанию лимитер работает в процессе, а при заданном REDIS_URL — общий через Redis. На нескольких инстансах без Redis каждый инстанс держит свои 600 — учитывайте это при планировании.

RATE_LIMITED и QUOTA_EXCEEDED — оба 429, но означают разное: первый снимается через секунды, второй — только с началом нового периода или после смены тарифа. Смотрите error.code, а не только статус.

Квоты тарифовCopy Anchor Link

Метрики учёта: searches, documents, ai_tokens и reindex. Включённые в тариф объёмы за период:

Цены превышения за блок:

У Free цен превышения нет вообще: при достижении лимита возвращается 429 QUOTA_EXCEEDED, и ничего не списывается. На платных тарифах превышение списывается с предоплаченного кошелька.

Функции, зависящие от тарифа: Free включает поиск по ключевым словам, синонимы, стоп-слова, aiAnswer (RAG, в пределах 10 000 AI-токенов) и scheduledSync, но не vectorSearch, hybridSearch, curations, grouping, geoSearch, multiSearch, reindex, exportDocuments, customSort и queryAnalytics. Использование закрытой функции даёт 402 PAYMENT_REQUIRED от слоя учёта; запрос падает, а не деградирует молча. Недостающий scope API-ключа по-прежнему даёт 403 FORBIDDEN.

Кошелёк и превышениеCopy Anchor Link

1. Расход считается по периоду (YYYY-MM) и сбрасывается в 00:00 UTC первого числа.
2. В пределах включённого объёма вызов ничего не стоит.
3. Сверх него каждый блок списывается с кошелька: searches блоками по 1 000, documents и ai_tokens так же, reindex — за запуск.
4. При нулевом балансе вызов падает с 402 PAYMENT_REQUIRED и инструкцией по пополнению; функция тарифа, требующая оплаты, падает так же.
5. Пополнения — предоплаченные пакеты на $10, $50 и $200, они покупаются через платёжного провайдера и попадают в журнал операций.

Смотрите состояние заранее:

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 считается по зеркалу документов, а не по счётчику, поэтому отражает фактическое содержимое индекса. wallet равен null, если у тенанта никогда не было пополнений.

Практические рекомендацииCopy Anchor Link

• Повторяйте только на 429. Заголовок Retry-After не отправляется; используйте details.reset_at или x-ratelimit-reset.
• Не повторяйте 4xx кроме 429. 403 не станет 200 от повторения, а тело с 422 нужно исправить.
• Повторяйте 5xx с джиттером. SDK по умолчанию делают две попытки с экспоненциальной задержкой.
• Следите за x-aac-quota-remaining. Падения на границе квоты можно избежать, если алертить на 10% остатка.
• Алертите по доле пустых выдач, а не по 200. Поиск без результатов — успех по HTTP и провал по продукту.