Errors

Error Format

Errors return JSON with a detail field:

{
  "detail": "Invalid or missing API key."
}

Validation errors (422) include field-level details:

{
  "detail": [
    {
      "loc": ["body", "query"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}

Status Codes

Code	Meaning	Action
`200`	Success
`400`	Bad Request	The request parsed but the API refused it. See 400 versus 422
`401`	Unauthorized	Check your API key and `Authorization` header
`402`	Payment Required	Check your account dashboard.
`403`	Forbidden	Your key lacks the required scope, or your plan does not include the feature. Webhook delivery is Business-only
`404`	Not Found	Resource does not exist
`409`	Conflict	You already hold this watch. See 409 on watches
`422`	Validation Error	Check request body for missing or invalid fields
`429`	Rate Limited	Back off and retry with exponential backoff. Also returned when you exceed your plan’s watch cap
`500`	Internal Error	Retry after a brief delay. Contact support if it persists

On 403, webhook delivery on a watch requires the Business plan: use channel: "email" or upgrade. On 429, the watch cap is 3 outside Business and 100 on Business.

400 versus 422

A 422 is schema validation: a field is missing, or its type or range is wrong. FastAPI rejects it before your request reaches any business logic, and the response carries the loc array shown above. A 400 is a request that is well-formed but not allowed. POST /watches and PATCH /watches/{id} return it for:

a scope the board cannot be narrowed by, or an actId scope that does not exist on that board,
a source that is not scopable at all, meaning a board whose scopable is false such as the Federal Register,
a missing webhookUrl or emailAddress for the channel you asked for, or one set on a channel that does not use it,
a webhookUrl the API refuses as a delivery target,
a webhookAuth.headerName that is not a legal header name, or outbound auth set on an email-only watch.

The detail string names the specific problem, so read it rather than retrying.

409 on watches

POST /watches returns 409 when you already hold a watch on the same board, the same channel, and the same scope. Watches are unique on that triple, so this means the subscription you were about to create already exists rather than that something went wrong. PATCH /watches/{id} returns it for the same reason, when narrowing a watch’s scope would collide with another watch you already hold. List your watches with GET /watches and reuse the existing one.

Rate Limiting

Limits are enforced per API key and scale with your plan. Every 429 response includes a Retry-After header. See Rate limits for the per-plan table and a full backoff implementation.

Troubleshooting

401 but my key is correct

Include the Bearer prefix: Authorization: Bearer vq_key_.... The key alone is rejected.

422 validation error

Set Content-Type: application/json. Check the loc field in the response to find the problematic field.

Rate limits

Per-plan request limits and a full backoff implementation.

Authentication

Create and manage your API key.

DATA COVERAGE

USE CASES

GET STARTED

CORE CONCEPTS

LAW CHANGE ALERTS

WORKING WITH THE API

GROUNDING AI

RECIPES

Error Format

Status Codes

400 versus 422

409 on watches

Rate Limiting

Troubleshooting

Rate limits

Authentication

​Error Format

​Status Codes

​400 versus 422

​409 on watches

​Rate Limiting

​Troubleshooting

​Related

Rate limits

Authentication

Error Format

Status Codes

400 versus 422

409 on watches

Rate Limiting

Troubleshooting

Related