change_reason_required

HTTP status: 422 Unprocessable Entity

The change touches a critical environment that requires a reason, and the request didn’t carry one. Nothing was written.

A change to one environment needs a reason when that environment requires one. A change that reaches every environment in the project, such as editing a segment or a variation or archiving a flag, needs a reason when any environment in the project requires one. The message names the environment or environments involved.

Common causes

• The request has no X-Intent-Reason header.
• The header is there but empty, or holds only whitespace or invisible characters.
• A script or CI job that worked before now writes to an environment someone has since made critical.
• The request turns off Require a change reason or Require typing the environment key. Turning either setting off always needs a reason, and an Admin or Owner token.

How to fix

• Retry the same request with an X-Intent-Reason header that says why you’re making the change. Encode it as percent-encoded UTF-8. Plain ASCII needs no encoding.
• In automation, pass the reason through from whatever triggered the run, such as the deploy, ticket or pull request, so the audit log points back at it.
• From the MCP server, add the tool’s reason argument.

Example

{
  "error": "change_reason_required",
  "message": "This change needs a reason because environment 'production' requires one. Send it in the X-Intent-Reason header.",
  "docs_url": "https://featureflip.io/docs/management-api/errors/change_reason_required"
}