> ## Documentation Index
> Fetch the complete documentation index at: https://vaquill.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Best Practices

> Get better results and build resilient integrations

A few habits make Vaquill integrations faster, cheaper, and more accurate. Follow these when you move from a prototype to production.

## Scope every query

Pass `corpusType` (and `state` for state-scoped corpora) on `POST /statutes/search`. Scoping does two things: it sharpens relevance by removing off-target jurisdictions, and it makes your [pages](/docs/api-guide/pagination) more predictable. An unscoped search ranks across the whole corpus, so a `state`-specific answer can be crowded out by federal or other-state matches.

```json theme={"theme":"github-dark"}
{ "query": "security deposit return deadline", "corpusType": "STATE", "state": "ca" }
```

## Discover before you search

Call `GET /statutes/coverage` first to learn what is queryable. Read a jurisdiction's `corpora` keys and pass one back as `corpusType`. This avoids guessing a token that has no data for that state and wasting a call on an empty result.

<Tip>
  Use `GET /statutes/codes?state=XX` to see the individual statutory codes (Penal, Civil, and so on) ingested for a state, and their section counts, when you want to explain a state's structure to a user.
</Tip>

## Cache coverage

Coverage grows weekly, not hourly. Cache the responses of `/statutes/coverage`, `/statutes/states`, and `/statutes/codes` for hours or a day rather than calling them on every request. They still count against your [rate limits](/docs/api-guide/rate-limits).

## Store the actId values you care about

The `actId` (for example `USC_T42_C21_S1983`) is the stable handle for a section. Once a search surfaces a section your product depends on, store its `actId` and go straight to `GET /statutes/section/{actId}` or `.../body` on later runs. That skips the search entirely.

## Retry on 429, handle 402

* On `429`, respect the `Retry-After` header and use exponential backoff. See [Rate limits](/docs/api-guide/rate-limits).
* On `402`, stop, surface a clear message, resolve it in your account dashboard, then retry.
* Both are expected in production. Build for them rather than treating them as fatal.

## Treat relevanceScore as a within-response rank

`relevanceScore` (0 to 1) orders results **within a single response**. It is a relative rank, not a calibrated confidence score. Do not compare scores across different queries and do not use a fixed threshold (for example "drop anything below 0.7") to decide what to keep. To narrow results, tighten `query`, `corpusType`, and `state` instead.

## Link users to official sources

Each result carries source links (`htmlUrl`, `pdfUrl`, `xmlUrl`, `textUrl`, `docxUrl`, `stateHtmlUrl`, `govInfoHtmlUrl`, `govInfoPdfUrl`, `externalUrl`; any may be null). For user-facing deep links, prefer the official government link (state legislature or govinfo.gov) so readers land on authoritative text. This keeps your product grounded and verifiable.

## Related

<CardGroup cols={2}>
  <Card title="Pagination" icon="list-ol" href="/docs/api-guide/pagination">
    Page predictably with `limit`, `offset`, and `hasMore`.
  </Card>

  <Card title="Coverage" icon="table" href="/docs/api-guide/coverage">
    See the full jurisdiction and corpus matrix.
  </Card>
</CardGroup>