Fehler und Limits

Der Fehler-UmschlagCopy Anchor Link

Jeder Fehler — Validierung, Auth, Kontingent, Engine — nutzt dieselbe Form:

{
	"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 ist ein stabiler Bezeichner, auf den Sie verzweigen können; message ist für Menschen und darf sich ändern; request_id kommt auch im Header x-request-id. details gibt es nur, wenn es etwas Nützliches zu sagen gibt.

curl -sS -i "$AAC_API/indexes/documentation/search?q=preise&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 nach StatusCopy Anchor Link

400Copy Anchor Link

401Copy Anchor Link

402Copy Anchor Link

403Copy Anchor Link

Ein acl-Claim in einer Suchanfrage wird ignoriert — nicht abgelehnt —, wenn der Schlüssel eine allowedOrigins-Liste hat oder der Request einen Origin-Header trägt: Ein im Browser sichtbarer Schlüssel kann nicht wählen, wessen Dokumente er sieht. Solche Suchen sehen nur Dokumente ohne ACL.

404Copy Anchor Link

409Copy Anchor Link

413Copy Anchor Link

422Copy Anchor Link

429Copy Anchor Link

5xxCopy Anchor Link

Engine- und Anbieterfehler werden auf diesen öffentlichen Vertrag abgebildet, bevor sie die API verlassen; interne Namen erscheinen nie in einer Antwort: 404 der Engine wird INDEX_NOT_FOUND, 409 wird INDEX_ALREADY_EXISTS, 400/422 werden INVALID_QUERY (ein unbekanntes Feld in filter_by/sort_by/facet_by/query_by/group_by wird FIELD_NOT_IN_SCHEMA), Timeouts werden SEARCH_TIMEOUT, alles andere (auch eine fehlende Engine-Konfiguration) wird SEARCH_UNAVAILABLE. Weitere Aliase: AI_PROVIDER_ERROR → AI_UNAVAILABLE, ENGINE_FEATURE_UNSUPPORTED → FEATURE_UNSUPPORTED, INDEX_HAS_NO_EMBEDDING_FIELD → INDEX_NOT_VECTOR_ENABLED. Die rohe Engine-Meldung wird serverseitig protokolliert und über request_id korreliert; nennen Sie diese ID dem Support.

Rate-LimitsCopy Anchor Link

Requests werden pro API-Schlüssel in einem gleitenden Fenster begrenzt:

Jede authentifizierte Antwort trägt x-ratelimit-limit, x-ratelimit-remaining und x-ratelimit-reset (Unix-Sekunden), auch erfolgreiche — ein Client kann sich also selbst takten. Überschreitung ergibt eine 429 mit Reset-Zeit:

curl -sS -i "$AAC_API/indexes/documentation/search?q=preise" \
  -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" }
	}
}

Der Limiter läuft standardmäßig im Prozess und über Redis geteilt, wenn REDIS_URL gesetzt ist. Hinter mehreren Instanzen ohne Redis setzt jede Instanz ihre eigenen 600 durch — planen Sie das bei der Dimensionierung ein.

RATE_LIMITED und QUOTA_EXCEEDED sind beide 429, bedeuten aber Verschiedenes: das erste erledigt sich in Sekunden, das zweite erst mit der nächsten Abrechnungsperiode oder einem Tarifwechsel. Lesen Sie error.code, nicht nur den Status.

TarifkontingenteCopy Anchor Link

Metriken sind searches, documents, ai_tokens und reindex. Inklusivmengen pro Abrechnungsperiode:

Überschreitungspreise pro Block:

Free hat überhaupt keine Überschreitungspreise: Beim Erreichen eines Limits kommt 429 QUOTA_EXCEEDED, und es wird nichts belastet. Bei bezahlten Tarifen wird die Überschreitung mit dem Prepaid-Wallet verrechnet.

Tarifgebundene Funktionen: Free enthält Keyword-Suche, Synonyme, Stopwords, aiAnswer (RAG, im Rahmen von 10.000 KI-Token) und scheduledSync, aber kein vectorSearch, hybridSearch, curations, grouping, geoSearch, multiSearch, reindex, exportDocuments, customSort oder queryAnalytics. Die Nutzung einer gesperrten Funktion liefert 402 PAYMENT_REQUIRED aus der Metering-Schicht; der Request scheitert, statt still zu degradieren. Fehlender API-Schlüssel-Scope liefert weiterhin 403 FORBIDDEN.

Wallet und ÜberschreitungCopy Anchor Link

1. Die Nutzung wird pro Periode (YYYY-MM) gezählt und am 1. um 00:00 UTC zurückgesetzt.
2. Bis zur Inklusivmenge kostet ein Aufruf nichts.
3. Darüber wird jeder Block aus dem Wallet belastet: searches in 1.000er-Blöcken, documents und ai_tokens ebenso, reindex pro Lauf.
4. Bei Nullguthaben scheitert der Aufruf mit 402 PAYMENT_REQUIRED und Aufladehinweis; eine kostenpflichtige Tariffunktion scheitert ebenso.
5. Aufladungen sind Prepaid-Pakete zu 10, 50 und 200 USD, gekauft über den Zahlungsanbieter und im Ledger verbucht.

Lesen Sie den Zustand, bevor er weh tut:

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 wird aus dem Dokument-Spiegel gezählt, nicht aus einem Zähler, und spiegelt damit den tatsächlichen Indexinhalt. wallet ist null, wenn der Mandant nie ein Guthaben hatte.

BetriebsempfehlungenCopy Anchor Link

• Nur bei 429 wiederholen. Retry-After wird nicht gesendet; nutzen Sie details.reset_at oder x-ratelimit-reset.
• Keine 4xx außer 429 wiederholen. Eine 403 wird durch Wiederholung nicht zur 200, ein 422-Body muss korrigiert werden.
• 5xx mit Jitter wiederholen. Die SDKs versuchen es standardmäßig zweimal mit exponentiellem Backoff.
• x-aac-quota-remaining beobachten. Ein Scheitern an der Kontingentgrenze ist vermeidbar, wenn Sie bei 10 % Restwarnen.
• Auf Null-Ergebnis-Rate alarmieren, nicht auf 200er. Eine Suche ohne Treffer ist per HTTP ein Erfolg und produktseitig ein Fehler.