Errors

Every Management API error returns the same JSON envelope. The error field is a stable, machine-readable code; docs_url links to the page for that code.

{
  "error": "not_found",
  "message": "Project 'checkout' was not found.",
  "docs_url": "https://featureflip.io/docs/management-api/errors/not_found"
}

See Conventions → Errors for every envelope field.

Error codes

Code	HTTP	Meaning
bad_request	400	Malformed or unprocessable request
validation_failed	400	One or more fields failed validation
unauthorized	401	Missing, invalid, expired, or revoked token
forbidden	403	Token’s role is insufficient
sso_required	403	The organization requires single sign-on and the token didn’t come through it
two_factor_required	403	The organization requires two-factor authentication and the token’s owner hasn’t turned it on
token_lifetime_exceeds_policy	403	The organization refuses personal access tokens that last longer than its limit, and this one does
plan_limit_reached	403	A create or restore would take the organization past one of its plan’s caps, or the request acts on a webhook subscription a downgrade left over one
organization_read_only	403	The organization is over its plan’s limits after a downgrade and is read-only until it fits
not_found	404	Resource doesn’t exist or isn’t visible
method_not_allowed	405	HTTP method not supported on this path
conflict	409	Another request changed or created the same resource first
idempotency_key_in_progress	409	A same-key create is still in flight
idempotency_key_reuse	409	The same key was used with a different request body
precondition_failed	412	The resource changed since the If-Match ETag you sent
unsupported_media_type	415	Content-Type was not application/json
change_reason_required	422	The change touches a critical environment that requires a reason, and the request sent none
rate_limited	429	Rate limit exceeded
internal_error	500	Unexpected server error