● Reference

Errors

One envelope, eleven codes. Eight transport codes, three domain gates. The gates are the contract: they encode legal and compliance reality and they never soft-pass.

{
  "error": {
    "code": "authority_required",
    "message": "No granted authority model on matter mtr_4Fa1.",
    "md_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 MD-Request-Id when contacting support.	transport
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, token-bucket:

Environment	Sustained	Burst
sandbox	25 req/s	50
production	100 req/s	200

Every response carries MD-RateLimit-Limit and MD-RateLimit-Remaining. When you exceed the limit you get a 429 rate_limited with a Retry-After header (seconds) — back off and retry; an exponential backoff that honors Retry-After is enough.

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

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

These numbers are provisional while we are pre-launch and enforcement is best-effort at the edge — a short burst may briefly see more headroom than published. Treat the published numbers as the contract; if you need sustained throughput above them, ask and we will raise your key.