Errors

All Florida Business 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 Business API is an independent data platform and is not affiliated with Sunbiz.org, the Florida Department of State, or the Florida Division of Corporations.

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": "Entity L00000000000 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
    }
  }
}