Gate Errors

Gate returns structured JSON errors with a machine-readable code and a human-readable message.

{
  "error": "Human readable message",
  "code": "service.error_name"
}

Validation errors also include a fields object with per-field messages.

Common Errors

Code	HTTP	Cause	Fix
`validation_error`	400	Invalid request body or parameters	Check `fields` for details. Ensure flag keys match `/^[a-z0-9][a-z0-9_-]*$/` and `enabled` is a boolean.
`unauthorized`	401	Missing or invalid API key	Add `Authorization: Bearer sm_...` header. See Authentication.
`forbidden`	403	Authenticated but not authorized	Verify you own the flag. Check API key scopes.
`not_found`	404	Resource does not exist	Verify the flag key. Use `GET /v1/gate` to list all flags.
`insufficient_balance`	402	Not enough credits for a billable operation	Only applies to `GET /v1/gate/config` and `GET /v1/gate/:flagKey`. See Pricing for tier details.
`rate_limit_exceeded`	429	Too many requests	Implement exponential backoff. Use `GET /v1/gate/config` instead of individual flag checks. See Rate Limits.

Code	HTTP	Cause	Fix
`gate.feature_not_found`	404	Flag does not exist	Verify spelling and case. Create the flag via `POST /v1/gate` if needed.
`gate.rule_invalid`	400	Malformed flag value	Gate uses boolean-only flags. Ensure values are `true` or `false`.
`gate.evaluation_failed`	500	Internal error during flag evaluation	Retry the request. If it persists, fall back to a safe default and contact support with the flag key and timestamp.

Always implement fallback defaults. If Gate returns an error, use a safe default (typically false).
Cache the last-known config locally. Serve stale data on failure rather than breaking the user experience.
Use bulk config for client SDKs. GET /v1/gate/config fetches all flags in one request. Poll every 30-60 seconds.
Flag updates propagate within 60 seconds. For time-sensitive changes, verify via the single-flag endpoint after updating.