Errors & Rate Limits

{
	"error": "error_code",
	"message": "Human-readable description of the error",
	"retryable": false,
	"requestId": "req_01HX9JKP7QZK7M5T2N4F8R6Y3W",
	"docsUrl": "https://docs.aacsearch.com/troubleshooting/auth-errors"
}

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 15
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1717201234

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit of 60 req/min exceeded. Retry after 15 seconds."
}

HTTP/1.1 429 Too Many Requests

{
  "error": "quota_exceeded",
  "message": "Monthly search-unit quota exhausted. Upgrade your plan or wait for reset."
}

import pRetry from "p-retry";

const results = await pRetry(() => client.search({ q: "headphones" }), {
	retries: 3,
	factor: 2,
	minTimeout: 1000,
	shouldRetry: (err) => err.status >= 500, // only retry server errors
});

import { SearchClient } from "@aacsearch/client";

try {
	const result = await client.search({ q: "shoes" });
} catch (err) {
	if (err instanceof AacSearchError) {
		console.error("aacsearch error", {
			code: err.code,
			requestId: err.requestId, // for support tickets
			traceId: err.traceId, // for distributed tracing dashboards
		});
	}
}

const result = await client.search(opts);
logger.info({
	event: "search.ok",
	requestId: result.requestId,
	searchTimeMs: result.searchTimeMs,
});

import { AacSearchError } from "@aacsearch/client";

try {
	await client.search({ q: "shoes" });
} catch (err) {
	if (err instanceof AacSearchError) {
		err.code; // string — error code from the body, stable
		err.message; // string — human-readable
		err.status; // number — HTTP status (0 for network errors)
		err.retryable; // boolean — derived from body, fall back to status >= 500
		err.requestId; // string | undefined
		err.traceId; // string | undefined
		err.docsUrl; // string | undefined
		err.response; // Response | undefined — raw fetch Response if available
	}
}

function SearchInvalidKey({ requestId }: { requestId?: string }) {
	return (
		<div role="alert" className="search-error">
			<h3>Search is not configured correctly</h3>
			<p>Your API key is invalid, expired, or has been revoked.</p>
			<p>
				If you are the site owner, generate a new key in the AACsearch dashboard. Otherwise, please
				try again later.
			</p>
			{requestId && <small>Reference: {requestId}</small>}
		</div>
	);
}

function SearchQuotaExceeded({ resetDate }: { resetDate: Date }) {
	return (
		<div role="alert" className="search-error">
			<h3>Search is temporarily unavailable</h3>
			<p>The site has reached its monthly search limit.</p>
			<p>Service will resume on {resetDate.toLocaleDateString()}.</p>
			<p>
				<a href="https://app.aacsearch.com/billing">Upgrade plan</a>
			</p>
		</div>
	);
}

function NoResults({ query }: { query: string }) {
	return (
		<div className="no-results">
			<h3>No results for &quot;{query}&quot;</h3>
			<p>Try a shorter query, different keywords, or browse our categories below.</p>
			<a href="/c/all">Browse all products →</a>
		</div>
	);
}

function SearchUnavailable({
	requestId,
	onRetry,
}: {
	requestId?: string;
	onRetry: () => void;
}) {
	return (
		<div role="alert" className="search-error">
			<h3>Search is temporarily unavailable</h3>
			<p>We could not reach the search service. Please try again in a moment.</p>
			<button onClick={onRetry}>Retry</button>
			{requestId && <small>Reference: {requestId}</small>}
		</div>
	);
}

function SearchResults({ query }: { query: string }) {
	const { data, error, refetch } = useQuery({
		queryKey: ["search", query],
		queryFn: () => client.search({ q: query }),
	});

	if (error instanceof AacSearchError) {
		switch (error.code) {
			case "unauthorized":
			case "invalid_or_revoked_key":
				return <SearchInvalidKey requestId={error.requestId} />;
			case "quota_exceeded":
				return <SearchQuotaExceeded resetDate={nextMonthFirst()} />;
			case "rate_limit":
			case "search_failed":
			case "service_unavailable":
				return <SearchUnavailable requestId={error.requestId} onRetry={refetch} />;
			default:
				return <SearchUnavailable requestId={error.requestId} onRetry={refetch} />;
		}
	}

	if (data?.found === 0) return <NoResults query={query} />;
	return <ResultGrid hits={data?.hits ?? []} />;
}