● Reference

Errors

One error envelope. Eight transport codes and three domain gates. Gates encode legal and compliance requirements and never soft-pass.

{
  "error": {
    "code": "authority_required",
    "message": "No granted authority model on matter mtr_4Fa1.",
    "request_id": "req_01JX4M..."
  }
}

Code	HTTP	Meaning	Class
invalid_request	400	Malformed body, unknown field, or failed validation.	transport
unauthenticated	401	Missing or invalid API key.	transport
quota_exceeded	402	The organization exceeded its plan's monthly metered-operation quota on a hard-block plan. Returned only when usage-based billing is enabled; reads, health, and capability checks are never quota-limited. Upgrade the plan or wait for the next billing period.	quota_error
insufficient_scope	403	Key lacks the scope this operation requires.	transport
not_found	404	No resource with this id exists in your organization and environment.	transport
conflict	409	Idempotency-Key reused with a different request body. Send a new key for a new request.	transport
rate_limited	429	Too many requests; honor Retry-After.	transport
internal_error	500	Something failed on our side. Safe to retry; include the Anvil-Request-Id when contacting support.	transport
endpoint_retired	410	This v2 operation was retired in v3. The message and doc_url name the successor operation or verb.	transport
verb_not_available	422	The verb is reserved in the catalog but its engine has not shipped. Nothing was queued.	domain gate
unknown_verb	422	Unknown job type inside a reserved namespace (crypto., disclose., restrain., judgment., execute., freeze., report.*).	domain gate
authority_required	409	No granted authority model on the parent matter. Never soft-passes.	domain gate
sanctions_gate	409	A sanctions screen hit blocks this operation pending review.	domain gate
stay_in_effect	409	An enforcement stay is in effect for this matter.	domain gate

Rate limits

Limits are per API key:

Plan	Sustained	Burst
Sandbox (kx_test_)	25 req/s	50
Operator (kx_live_)	100 req/s	200
Institutional	custom	custom

Every response carries Anvil-RateLimit-Limit and Anvil-RateLimit-Remaining. When you exceed the limit you get a 429 rate_limited with a Retry-After header (seconds). Retry with exponential backoff, honoring Retry-After.

HTTP/2 429
Retry-After: 1
Anvil-RateLimit-Limit: 25
Anvil-RateLimit-Remaining: 0

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded for this key (25 req/s sustained). Retry after 1s.",
    "request_id": "req_01JX..."
  }
}

Limits are enforced per key. Institutional plans carry custom limits; Operator limits can be raised on request.