Errors

All Florida Tax Certificate API errors return a uniform JSON envelope. The shape is identical across REST endpoints; the MCP server wraps the same code / message inside a JSON-RPC error.

Florida Tax Certificate API is an independent data platform and is not affiliated with the Florida Department of Revenue, any county tax collector or clerk of court, LienHub, RealAuction / RealTaxLien, or TaxCertSale.

REST Envelope

{
  "error": {
    "code": "bad_request",
    "message": "Human-readable description of what went wrong.",
    "request_id": "req_1234567890abcdef12345"
  }
}

Every response — success or failure — includes a request_id. Quote it when filing support tickets so we can pull the matching server log.

Codes

Code	HTTP	Meaning
bad_request	400	Query params failed validation.
unauthorized	401	Missing, invalid, or revoked API key. See Authentication.
payment_required	402	Workspace credit balance is empty and auto-topup is disabled.
forbidden	403	Authenticated but not permitted for this resource (e.g. MCP-only tier hitting REST).
rest_disabled	403	Your plan's surfaces array does not include rest — see below.
not_found	404	Resource does not exist.
rate_limited	429	Per-key RPM or monthly quota exceeded. Retry-After header included.
internal_error	5xx	Server-side failure. Reference request_id in support tickets.

400 bad_request

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "code": "bad_request",
    "message": "limit must be between 1 and 500.",
    "request_id": "req_1234567890abcdef12345"
  }
}

401 unauthorized

Same shape for missing / invalid / revoked / wrong-workspace keys (no oracle):

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key.",
    "request_id": "req_1234567890abcdef12345"
  }
}

402 payment_required

Returned when a metered request needs to draw credits and the workspace balance is empty with auto-topup off.

{
  "error": {
    "code": "payment_required",
    "message": "Credit balance is zero. Enable auto-topup or purchase a credit pack.",
    "request_id": "req_1234567890abcdef12345"
  }
}

403 rest_disabled

The MCP Starter tier ($5/mo, 1,000 MCP calls) does not include the /api/v1/* REST surface. The key authenticates correctly, but the REST router rejects the request:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "error": {
    "code": "rest_disabled",
    "message": "This plan does not include REST API access. Use the MCP transport or upgrade to a tier that includes REST.",
    "request_id": "req_1234567890abcdef12345"
  }
}

Upgrade to Developer or higher to add rest to your plan's surfaces.

404 not_found

{
  "error": {
    "code": "not_found",
    "message": "Certificate not found.",
    "request_id": "req_1234567890abcdef12345"
  }
}

429 rate_limited

Sent when you exceed either the per-minute rate limit or the monthly quota. The Retry-After header tells you when to retry (seconds).

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 17
RateLimit-Limit: 120
RateLimit-Remaining: 0
RateLimit-Reset: 17

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Retry after 17 seconds.",
    "request_id": "req_1234567890abcdef12345"
  }
}

See Rate Limits for per-tier limits.

5xx internal_error

{
  "error": {
    "code": "internal_error",
    "message": "An unexpected error occurred.",
    "request_id": "req_1234567890abcdef12345"
  }
}

Retry with exponential backoff. If the same request_id reproduces consistently, open a support ticket with the ID — we keep request-scoped logs for 30 days.

MCP / JSON-RPC Errors

The MCP server at /api/mcp wraps the same condition set inside a JSON-RPC 2.0 error frame. Codes:

JSON-RPC Code	Meaning
-32600	Invalid Request — malformed JSON-RPC envelope.
-32601	Method not found — tool name does not exist.
-32602	Invalid params — tool argument validation failed (mirrors REST bad_request).
-32603	Internal error — mirrors REST internal_error.
-32001	Unauthorized — mirrors REST unauthorized.
-32004	Out of credits — workspace credit balance is zero (mirrors REST payment_required).
-32029	Rate limited — mirrors REST rate_limited. Retry-after seconds in data.retry_after.

Example out-of-credits response:

{
  "jsonrpc": "2.0",
  "id": 7,
  "error": {
    "code": -32004,
    "message": "Out of credits. Enable auto-topup or purchase a credit pack.",
    "data": {
      "request_id": "req_1234567890abcdef12345",
      "credit_balance": 0
    }
  }
}