Errors

The error envelope

Every 4xx and 5xx response uses one envelope:

{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed.",
    "request_id": "9f1c2e7a-7b3d-4c1e-8a0a-2f6b1c4d5e6f"
  }
}

• code — a stable, machine-readable string from the table below. Branch on this, not on the human message.
• message — a human-readable summary. Safe to log or surface; not guaranteed to be stable across releases.
• request_id — mirrors the X-Request-Id header. Quote it in support requests.

Validation errors carry details

A validation_error (HTTP 400) adds a details object mapping each rejected field to its messages, while the top-level message stays a stable generic string:

{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed.",
    "request_id": "…",
    "details": {
      "fips": ["This field is required."],
      "page_size": ["Ensure this value is less than or equal to 500."]
    }
  }
}

Error codes

Code	HTTP	Meaning
unauthorized	401	Missing or invalid credentials.
forbidden	403	Authenticated, but not permitted.
subscription_required	402	A Pro subscription is required to use the API.
tier_upgrade_required	402	Your plan doesn’t include REST access (on the Free plan, use the MCP server or upgrade).
usage_limit_exceeded	402	Usage cap for your plan reached; resets at the start of your next billing period.
validation_error	400	Invalid request parameters. Carries a details field.
not_found	404	The resource does not exist.
method_not_allowed	405	HTTP method not supported on this endpoint.
rate_limited	429	Too many requests — back off and retry. See Rate limits.
internal_error	500	An unexpected server error.

Errors are never billed: X-Tokens-Used is 0 on any error response.