API errors

HTTP status codes

Polyfence uses standard HTTP semantics. The status tells you the failure class; the code field tells you the specific, stable cause — branch on code, never on the human message.

Error envelope

Every error response is the same flat shape. Branch on the machine-readable code (a closed enum) — never parse the human message. error is a short title (the category); message is the specific, human-readable detail (free to change/localise).

{
  "success": false,
  "code": "not_found",
  "error": "Not found",
  "message": "Zone not found"
}

// Validation errors add an "errors" array with field-level detail:
{
  "success": false,
  "code": "validation_error",
  "error": "Validation error",
  "message": "Zone data validation failed",
  "errors": [
    { "field": "radius_meters", "rule": "min", "value": 0 }
  ]
}

// Quota errors carry tier context on the root for the upgrade flow:
{
  "success": false,
  "code": "quota_exceeded",
  "error": "Quota exceeded",
  "message": "Zone limit reached",
  "current": 100, "limit": 100, "tier": "free", "upgradeUrl": "/account?tab=plan"
}

The full list of code values is a closed enum — see the typed ErrorCode in the OpenAPI spec and the generated SDKs (v2.0.0+).

Authentication

Most endpoints accept either a session cookie or an `x-api-key` header (dual auth). A few are session-only (e.g. device provisioning, account deletion) and a few are key-only — the row below names the case where it matters. Authentication is checked BEFORE body/parameter validation, so a malformed request with no/invalid key returns an auth error, not a validation error.

Rate limits

Polyfence enforces 50 requests per second per identifier during Early Access. `rate_limited` responses are 429 and include a Retry-After header. NOTE: monthly tier quotas are a SEPARATE failure class — they return 403 `quota_exceeded` (see Tier limits), not 429. A 429 always means “slow down,” never “out of quota.”

Tier limits

Polyfence's tier system enforces quotas on zones, API calls, and active API keys. Hits return 403 `quota_exceeded` (distinct from 429 `rate_limited`, so clients can tell “out of quota” from “slow down”). During Early Access most quotas are unlimited; the pricing flip moves these to Free/Pro tier values.

Validation

Request bodies are validated with Zod schemas. Validation failures return 400 `validation_error` (or a more specific code like `invalid_json` / `invalid_id`) with a message naming the offending field or rule.

Not found

Polyfence returns 404 `not_found` both for genuinely missing resources and for cross-tenant access attempts. The two are intentionally indistinguishable to avoid resource enumeration.

Conflict / idempotency

Mostly relevant to device provisioning and bulk operations. 409 `conflict` responses signal a state collision rather than a malformed request.

Connector / SSRF

Data connector endpoints reject URLs targeting private networks, localhost, link-local, and cloud metadata services. Validation runs both at config-save time AND at fetch time (DNS rebinding protection). These reject with 400 `validation_error`; an oversized fetched body returns 413 `payload_too_large`.

Subscription

Billing-related endpoints (currently routed via Polar). Most users won't hit these during Early Access.