Skip to content

Resumes a paused ramp, accepting the rule as it stands now, and honours the rest of the hold it had when paused.

POST
/api/v1/orgs/{org}/projects/{project}/flags/{flag}/environments/{env}/ramps/{rampId}/resume
curl --request POST \
--url https://api.featureflip.io/api/v1/orgs/example/projects/example/flags/example/environments/example/ramps/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/resume \
--header 'Authorization: <Authorization>'

Requires at least Member.

org
required
string
project
required
string
flag
required
string
env
required
string
rampId
required
string format: uuid
If-Match
string

Optional. The ETag from a GET of this resource. The write applies only if the resource still has that ETag, meaning nothing in its body has changed since; otherwise 412 precondition_failed. * or no header applies the write unconditionally.

X-Intent-Reason
string

Why you are making this change, recorded in the audit log. Percent-encoded UTF-8 (encode it the way encodeURIComponent does); at most 2048 characters after decoding. Required when the target environment — or, for project-wide changes, any environment in the project — requires a change reason; without one the request is refused with 422 change_reason_required.

X-Freeze-Override
boolean

Owner/Admin only: true breaks an active change freeze for this one request; requires X-Intent-Reason.

OK

Media type application/json

A rollout ramp (#4653, #5180) as /api/v1 returns it. Flag and environment are implicit in the route. A ramp drives either a targeting rule (RuleId set) or the default rule (IsDefaultRule true, TargetVariationId the variation it rolls out). Status is Running, Paused, Completed or Aborted. CurrentStepIndex is the step last applied, -1 before the first. NextStepAt is set only while running and not yet on the last step.

object
id
required
string format: uuid
ruleId
string format: uuid
nullable
isDefaultRule
required
boolean
targetVariationId
string format: uuid
nullable
status
required
string
steps
required
Array<object>

One rung of a rollout ramp: the percentage served, then how long it holds before the next rung. Both fields are required.

object
percent
required
integer format: int32
holdMinutes
required
integer format: int32
currentStepIndex
required
integer format: int32
nextStepAt
string format: date-time
nullable
pausedReason
string
nullable
pausedDetail
string
nullable
startedByName
string
nullable
createdAt
required
string format: date-time
completedAt
string format: date-time
nullable
abortedAt
string format: date-time
nullable

Example generated

{
"id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
"ruleId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
"isDefaultRule": true,
"targetVariationId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
"status": "example",
"steps": [
{
"percent": 1,
"holdMinutes": 1
}
],
"currentStepIndex": 1,
"nextStepAt": "2026-04-15T12:00:00Z",
"pausedReason": "example",
"pausedDetail": "example",
"startedByName": "example",
"createdAt": "2026-04-15T12:00:00Z",
"completedAt": "2026-04-15T12:00:00Z",
"abortedAt": "2026-04-15T12:00:00Z"
}
ETag
string

Strong ETag of the resource’s whole body as sent to this caller: it changes whenever anything in the body does. Send it back as If-Match on a PUT.

X-RateLimit-Limit
integer

The maximum number of requests permitted per rate-limit window for this caller.

X-RateLimit-Remaining
integer

The number of requests remaining in the current rate-limit window.

X-RateLimit-Reset
integer

The UTC time at which the current rate-limit window resets, as a Unix timestamp in seconds.

Bad Request

Media type application/json

The frozen public-API error contract. error codes are stable snake_case strings. Wire keys are frozen snake_case too (error, message, docs_url, fields, retry_after) — the global camelCase naming policy would otherwise emit docsUrl/retryAfter, breaking the published spec. !:JsonPropertyName always wins over the policy, so these are pinned explicitly rather than relying on the property names already being lowercase for the single-word ones. did_you_mean, next_actions and connection_id are ADDITIVE optional keys (null → omitted via the global DefaultIgnoreCondition = WhenWritingNull), so pre-existing error bodies are byte-for-byte unchanged when they’re absent.

connection_id is present only on the sso_required error: the organization requires single sign-on, and this credential didn’t come through its identity provider. connection_id identifies which SSO connection to sign in with. plan_limit is present only on the plan_limit_reached error: which plan cap the request would have exceeded, so a client can branch on it without parsing message. change_freeze is present only on the change_frozen error (#4645): the change freeze that refused the write, so a client can show when it ends and whether the caller may break it, without parsing message.

object
error
required
string
message
required
string
docs_url
required
string
fields
object
key
additional properties
Array<string>
retry_after
integer format: int32
nullable
did_you_mean
Array<string>
nullable
next_actions
Array<object>
nullable
object
method
required
string
path
required
string
connection_id
string format: uuid
nullable
plan_limit

The cap behind a plan_limit_reached error. resource is the capped collection (projects, environments, flags, webhooks, members); plan is the plan’s wire name, as GET /api/v1/orgs/{org} returns it; max is the cap. The environment and flag caps are per project.

object
resource
required
string
plan
required
string
max
required
integer format: int32
change_freeze

The freeze behind a change_frozen error: id and name of the window, the environment’s environment_key, ends_at (UTC; always present, null for an open-ended window) and whether the caller’s role may break it (can_override, with X-Freeze-Override: true and an X-Intent-Reason).

object
id
required
string format: uuid
name
required
string
environment_key
required
string
ends_at
string format: date-time
nullable
can_override
required
boolean

Example

{
"error": "not_found",
"message": "Flag 'new-checkout-flw' was not found in project 'checkout'.",
"docs_url": "https://featureflip.io/docs/management-api/errors/not_found",
"did_you_mean": [
"new-checkout-flow"
],
"next_actions": [
{
"method": "GET",
"path": "/api/v1/orgs/acme/projects/checkout/flags"
}
]
}
X-RateLimit-Limit
integer

The maximum number of requests permitted per rate-limit window for this caller.

X-RateLimit-Remaining
integer

The number of requests remaining in the current rate-limit window.

X-RateLimit-Reset
integer

The UTC time at which the current rate-limit window resets, as a Unix timestamp in seconds.

Authentication is required, or the supplied API token is invalid or expired.

Media type application/json

The frozen public-API error contract. error codes are stable snake_case strings. Wire keys are frozen snake_case too (error, message, docs_url, fields, retry_after) — the global camelCase naming policy would otherwise emit docsUrl/retryAfter, breaking the published spec. !:JsonPropertyName always wins over the policy, so these are pinned explicitly rather than relying on the property names already being lowercase for the single-word ones. did_you_mean, next_actions and connection_id are ADDITIVE optional keys (null → omitted via the global DefaultIgnoreCondition = WhenWritingNull), so pre-existing error bodies are byte-for-byte unchanged when they’re absent.

connection_id is present only on the sso_required error: the organization requires single sign-on, and this credential didn’t come through its identity provider. connection_id identifies which SSO connection to sign in with. plan_limit is present only on the plan_limit_reached error: which plan cap the request would have exceeded, so a client can branch on it without parsing message. change_freeze is present only on the change_frozen error (#4645): the change freeze that refused the write, so a client can show when it ends and whether the caller may break it, without parsing message.

object
error
required
string
message
required
string
docs_url
required
string
fields
object
key
additional properties
Array<string>
retry_after
integer format: int32
nullable
did_you_mean
Array<string>
nullable
next_actions
Array<object>
nullable
object
method
required
string
path
required
string
connection_id
string format: uuid
nullable
plan_limit

The cap behind a plan_limit_reached error. resource is the capped collection (projects, environments, flags, webhooks, members); plan is the plan’s wire name, as GET /api/v1/orgs/{org} returns it; max is the cap. The environment and flag caps are per project.

object
resource
required
string
plan
required
string
max
required
integer format: int32
change_freeze

The freeze behind a change_frozen error: id and name of the window, the environment’s environment_key, ends_at (UTC; always present, null for an open-ended window) and whether the caller’s role may break it (can_override, with X-Freeze-Override: true and an X-Intent-Reason).

object
id
required
string format: uuid
name
required
string
environment_key
required
string
ends_at
string format: date-time
nullable
can_override
required
boolean

Example

{
"error": "not_found",
"message": "Flag 'new-checkout-flw' was not found in project 'checkout'.",
"docs_url": "https://featureflip.io/docs/management-api/errors/not_found",
"did_you_mean": [
"new-checkout-flow"
],
"next_actions": [
{
"method": "GET",
"path": "/api/v1/orgs/acme/projects/checkout/flags"
}
]
}
X-RateLimit-Limit
integer

The maximum number of requests permitted per rate-limit window for this caller.

X-RateLimit-Remaining
integer

The number of requests remaining in the current rate-limit window.

X-RateLimit-Reset
integer

The UTC time at which the current rate-limit window resets, as a Unix timestamp in seconds.

Forbidden

Media type application/json

The frozen public-API error contract. error codes are stable snake_case strings. Wire keys are frozen snake_case too (error, message, docs_url, fields, retry_after) — the global camelCase naming policy would otherwise emit docsUrl/retryAfter, breaking the published spec. !:JsonPropertyName always wins over the policy, so these are pinned explicitly rather than relying on the property names already being lowercase for the single-word ones. did_you_mean, next_actions and connection_id are ADDITIVE optional keys (null → omitted via the global DefaultIgnoreCondition = WhenWritingNull), so pre-existing error bodies are byte-for-byte unchanged when they’re absent.

connection_id is present only on the sso_required error: the organization requires single sign-on, and this credential didn’t come through its identity provider. connection_id identifies which SSO connection to sign in with. plan_limit is present only on the plan_limit_reached error: which plan cap the request would have exceeded, so a client can branch on it without parsing message. change_freeze is present only on the change_frozen error (#4645): the change freeze that refused the write, so a client can show when it ends and whether the caller may break it, without parsing message.

object
error
required
string
message
required
string
docs_url
required
string
fields
object
key
additional properties
Array<string>
retry_after
integer format: int32
nullable
did_you_mean
Array<string>
nullable
next_actions
Array<object>
nullable
object
method
required
string
path
required
string
connection_id
string format: uuid
nullable
plan_limit

The cap behind a plan_limit_reached error. resource is the capped collection (projects, environments, flags, webhooks, members); plan is the plan’s wire name, as GET /api/v1/orgs/{org} returns it; max is the cap. The environment and flag caps are per project.

object
resource
required
string
plan
required
string
max
required
integer format: int32
change_freeze

The freeze behind a change_frozen error: id and name of the window, the environment’s environment_key, ends_at (UTC; always present, null for an open-ended window) and whether the caller’s role may break it (can_override, with X-Freeze-Override: true and an X-Intent-Reason).

object
id
required
string format: uuid
name
required
string
environment_key
required
string
ends_at
string format: date-time
nullable
can_override
required
boolean

Example

{
"error": "not_found",
"message": "Flag 'new-checkout-flw' was not found in project 'checkout'.",
"docs_url": "https://featureflip.io/docs/management-api/errors/not_found",
"did_you_mean": [
"new-checkout-flow"
],
"next_actions": [
{
"method": "GET",
"path": "/api/v1/orgs/acme/projects/checkout/flags"
}
]
}
X-RateLimit-Limit
integer

The maximum number of requests permitted per rate-limit window for this caller.

X-RateLimit-Remaining
integer

The number of requests remaining in the current rate-limit window.

X-RateLimit-Reset
integer

The UTC time at which the current rate-limit window resets, as a Unix timestamp in seconds.

Not Found

Media type application/json

The frozen public-API error contract. error codes are stable snake_case strings. Wire keys are frozen snake_case too (error, message, docs_url, fields, retry_after) — the global camelCase naming policy would otherwise emit docsUrl/retryAfter, breaking the published spec. !:JsonPropertyName always wins over the policy, so these are pinned explicitly rather than relying on the property names already being lowercase for the single-word ones. did_you_mean, next_actions and connection_id are ADDITIVE optional keys (null → omitted via the global DefaultIgnoreCondition = WhenWritingNull), so pre-existing error bodies are byte-for-byte unchanged when they’re absent.

connection_id is present only on the sso_required error: the organization requires single sign-on, and this credential didn’t come through its identity provider. connection_id identifies which SSO connection to sign in with. plan_limit is present only on the plan_limit_reached error: which plan cap the request would have exceeded, so a client can branch on it without parsing message. change_freeze is present only on the change_frozen error (#4645): the change freeze that refused the write, so a client can show when it ends and whether the caller may break it, without parsing message.

object
error
required
string
message
required
string
docs_url
required
string
fields
object
key
additional properties
Array<string>
retry_after
integer format: int32
nullable
did_you_mean
Array<string>
nullable
next_actions
Array<object>
nullable
object
method
required
string
path
required
string
connection_id
string format: uuid
nullable
plan_limit

The cap behind a plan_limit_reached error. resource is the capped collection (projects, environments, flags, webhooks, members); plan is the plan’s wire name, as GET /api/v1/orgs/{org} returns it; max is the cap. The environment and flag caps are per project.

object
resource
required
string
plan
required
string
max
required
integer format: int32
change_freeze

The freeze behind a change_frozen error: id and name of the window, the environment’s environment_key, ends_at (UTC; always present, null for an open-ended window) and whether the caller’s role may break it (can_override, with X-Freeze-Override: true and an X-Intent-Reason).

object
id
required
string format: uuid
name
required
string
environment_key
required
string
ends_at
string format: date-time
nullable
can_override
required
boolean

Example

{
"error": "not_found",
"message": "Flag 'new-checkout-flw' was not found in project 'checkout'.",
"docs_url": "https://featureflip.io/docs/management-api/errors/not_found",
"did_you_mean": [
"new-checkout-flow"
],
"next_actions": [
{
"method": "GET",
"path": "/api/v1/orgs/acme/projects/checkout/flags"
}
]
}
X-RateLimit-Limit
integer

The maximum number of requests permitted per rate-limit window for this caller.

X-RateLimit-Remaining
integer

The number of requests remaining in the current rate-limit window.

X-RateLimit-Reset
integer

The UTC time at which the current rate-limit window resets, as a Unix timestamp in seconds.

Conflict

Media type application/json

The frozen public-API error contract. error codes are stable snake_case strings. Wire keys are frozen snake_case too (error, message, docs_url, fields, retry_after) — the global camelCase naming policy would otherwise emit docsUrl/retryAfter, breaking the published spec. !:JsonPropertyName always wins over the policy, so these are pinned explicitly rather than relying on the property names already being lowercase for the single-word ones. did_you_mean, next_actions and connection_id are ADDITIVE optional keys (null → omitted via the global DefaultIgnoreCondition = WhenWritingNull), so pre-existing error bodies are byte-for-byte unchanged when they’re absent.

connection_id is present only on the sso_required error: the organization requires single sign-on, and this credential didn’t come through its identity provider. connection_id identifies which SSO connection to sign in with. plan_limit is present only on the plan_limit_reached error: which plan cap the request would have exceeded, so a client can branch on it without parsing message. change_freeze is present only on the change_frozen error (#4645): the change freeze that refused the write, so a client can show when it ends and whether the caller may break it, without parsing message.

object
error
required
string
message
required
string
docs_url
required
string
fields
object
key
additional properties
Array<string>
retry_after
integer format: int32
nullable
did_you_mean
Array<string>
nullable
next_actions
Array<object>
nullable
object
method
required
string
path
required
string
connection_id
string format: uuid
nullable
plan_limit

The cap behind a plan_limit_reached error. resource is the capped collection (projects, environments, flags, webhooks, members); plan is the plan’s wire name, as GET /api/v1/orgs/{org} returns it; max is the cap. The environment and flag caps are per project.

object
resource
required
string
plan
required
string
max
required
integer format: int32
change_freeze

The freeze behind a change_frozen error: id and name of the window, the environment’s environment_key, ends_at (UTC; always present, null for an open-ended window) and whether the caller’s role may break it (can_override, with X-Freeze-Override: true and an X-Intent-Reason).

object
id
required
string format: uuid
name
required
string
environment_key
required
string
ends_at
string format: date-time
nullable
can_override
required
boolean

Example

{
"error": "not_found",
"message": "Flag 'new-checkout-flw' was not found in project 'checkout'.",
"docs_url": "https://featureflip.io/docs/management-api/errors/not_found",
"did_you_mean": [
"new-checkout-flow"
],
"next_actions": [
{
"method": "GET",
"path": "/api/v1/orgs/acme/projects/checkout/flags"
}
]
}
X-RateLimit-Limit
integer

The maximum number of requests permitted per rate-limit window for this caller.

X-RateLimit-Remaining
integer

The number of requests remaining in the current rate-limit window.

X-RateLimit-Reset
integer

The UTC time at which the current rate-limit window resets, as a Unix timestamp in seconds.

The resource changed since the If-Match ETag.

Media type application/json

The frozen public-API error contract. error codes are stable snake_case strings. Wire keys are frozen snake_case too (error, message, docs_url, fields, retry_after) — the global camelCase naming policy would otherwise emit docsUrl/retryAfter, breaking the published spec. !:JsonPropertyName always wins over the policy, so these are pinned explicitly rather than relying on the property names already being lowercase for the single-word ones. did_you_mean, next_actions and connection_id are ADDITIVE optional keys (null → omitted via the global DefaultIgnoreCondition = WhenWritingNull), so pre-existing error bodies are byte-for-byte unchanged when they’re absent.

connection_id is present only on the sso_required error: the organization requires single sign-on, and this credential didn’t come through its identity provider. connection_id identifies which SSO connection to sign in with. plan_limit is present only on the plan_limit_reached error: which plan cap the request would have exceeded, so a client can branch on it without parsing message. change_freeze is present only on the change_frozen error (#4645): the change freeze that refused the write, so a client can show when it ends and whether the caller may break it, without parsing message.

object
error
required
string
message
required
string
docs_url
required
string
fields
object
key
additional properties
Array<string>
retry_after
integer format: int32
nullable
did_you_mean
Array<string>
nullable
next_actions
Array<object>
nullable
object
method
required
string
path
required
string
connection_id
string format: uuid
nullable
plan_limit

The cap behind a plan_limit_reached error. resource is the capped collection (projects, environments, flags, webhooks, members); plan is the plan’s wire name, as GET /api/v1/orgs/{org} returns it; max is the cap. The environment and flag caps are per project.

object
resource
required
string
plan
required
string
max
required
integer format: int32
change_freeze

The freeze behind a change_frozen error: id and name of the window, the environment’s environment_key, ends_at (UTC; always present, null for an open-ended window) and whether the caller’s role may break it (can_override, with X-Freeze-Override: true and an X-Intent-Reason).

object
id
required
string format: uuid
name
required
string
environment_key
required
string
ends_at
string format: date-time
nullable
can_override
required
boolean

Example

{
"error": "not_found",
"message": "Flag 'new-checkout-flw' was not found in project 'checkout'.",
"docs_url": "https://featureflip.io/docs/management-api/errors/not_found",
"did_you_mean": [
"new-checkout-flow"
],
"next_actions": [
{
"method": "GET",
"path": "/api/v1/orgs/acme/projects/checkout/flags"
}
]
}
X-RateLimit-Limit
integer

The maximum number of requests permitted per rate-limit window for this caller.

X-RateLimit-Remaining
integer

The number of requests remaining in the current rate-limit window.

X-RateLimit-Reset
integer

The UTC time at which the current rate-limit window resets, as a Unix timestamp in seconds.

A change reason is required: this change affects an environment that requires one (error code change_reason_required). Retry with the X-Intent-Reason header.

Media type application/json

The frozen public-API error contract. error codes are stable snake_case strings. Wire keys are frozen snake_case too (error, message, docs_url, fields, retry_after) — the global camelCase naming policy would otherwise emit docsUrl/retryAfter, breaking the published spec. !:JsonPropertyName always wins over the policy, so these are pinned explicitly rather than relying on the property names already being lowercase for the single-word ones. did_you_mean, next_actions and connection_id are ADDITIVE optional keys (null → omitted via the global DefaultIgnoreCondition = WhenWritingNull), so pre-existing error bodies are byte-for-byte unchanged when they’re absent.

connection_id is present only on the sso_required error: the organization requires single sign-on, and this credential didn’t come through its identity provider. connection_id identifies which SSO connection to sign in with. plan_limit is present only on the plan_limit_reached error: which plan cap the request would have exceeded, so a client can branch on it without parsing message. change_freeze is present only on the change_frozen error (#4645): the change freeze that refused the write, so a client can show when it ends and whether the caller may break it, without parsing message.

object
error
required
string
message
required
string
docs_url
required
string
fields
object
key
additional properties
Array<string>
retry_after
integer format: int32
nullable
did_you_mean
Array<string>
nullable
next_actions
Array<object>
nullable
object
method
required
string
path
required
string
connection_id
string format: uuid
nullable
plan_limit

The cap behind a plan_limit_reached error. resource is the capped collection (projects, environments, flags, webhooks, members); plan is the plan’s wire name, as GET /api/v1/orgs/{org} returns it; max is the cap. The environment and flag caps are per project.

object
resource
required
string
plan
required
string
max
required
integer format: int32
change_freeze

The freeze behind a change_frozen error: id and name of the window, the environment’s environment_key, ends_at (UTC; always present, null for an open-ended window) and whether the caller’s role may break it (can_override, with X-Freeze-Override: true and an X-Intent-Reason).

object
id
required
string format: uuid
name
required
string
environment_key
required
string
ends_at
string format: date-time
nullable
can_override
required
boolean

Example

{
"error": "not_found",
"message": "Flag 'new-checkout-flw' was not found in project 'checkout'.",
"docs_url": "https://featureflip.io/docs/management-api/errors/not_found",
"did_you_mean": [
"new-checkout-flow"
],
"next_actions": [
{
"method": "GET",
"path": "/api/v1/orgs/acme/projects/checkout/flags"
}
]
}
X-RateLimit-Limit
integer

The maximum number of requests permitted per rate-limit window for this caller.

X-RateLimit-Remaining
integer

The number of requests remaining in the current rate-limit window.

X-RateLimit-Reset
integer

The UTC time at which the current rate-limit window resets, as a Unix timestamp in seconds.

A change freeze covers this environment (error code change_frozen; the change_freeze object names the window, when it ends and whether the caller may break it). An Owner or Admin can retry with X-Freeze-Override: true and an X-Intent-Reason.

Media type application/json

The frozen public-API error contract. error codes are stable snake_case strings. Wire keys are frozen snake_case too (error, message, docs_url, fields, retry_after) — the global camelCase naming policy would otherwise emit docsUrl/retryAfter, breaking the published spec. !:JsonPropertyName always wins over the policy, so these are pinned explicitly rather than relying on the property names already being lowercase for the single-word ones. did_you_mean, next_actions and connection_id are ADDITIVE optional keys (null → omitted via the global DefaultIgnoreCondition = WhenWritingNull), so pre-existing error bodies are byte-for-byte unchanged when they’re absent.

connection_id is present only on the sso_required error: the organization requires single sign-on, and this credential didn’t come through its identity provider. connection_id identifies which SSO connection to sign in with. plan_limit is present only on the plan_limit_reached error: which plan cap the request would have exceeded, so a client can branch on it without parsing message. change_freeze is present only on the change_frozen error (#4645): the change freeze that refused the write, so a client can show when it ends and whether the caller may break it, without parsing message.

object
error
required
string
message
required
string
docs_url
required
string
fields
object
key
additional properties
Array<string>
retry_after
integer format: int32
nullable
did_you_mean
Array<string>
nullable
next_actions
Array<object>
nullable
object
method
required
string
path
required
string
connection_id
string format: uuid
nullable
plan_limit

The cap behind a plan_limit_reached error. resource is the capped collection (projects, environments, flags, webhooks, members); plan is the plan’s wire name, as GET /api/v1/orgs/{org} returns it; max is the cap. The environment and flag caps are per project.

object
resource
required
string
plan
required
string
max
required
integer format: int32
change_freeze

The freeze behind a change_frozen error: id and name of the window, the environment’s environment_key, ends_at (UTC; always present, null for an open-ended window) and whether the caller’s role may break it (can_override, with X-Freeze-Override: true and an X-Intent-Reason).

object
id
required
string format: uuid
name
required
string
environment_key
required
string
ends_at
string format: date-time
nullable
can_override
required
boolean

Example

{
"error": "not_found",
"message": "Flag 'new-checkout-flw' was not found in project 'checkout'.",
"docs_url": "https://featureflip.io/docs/management-api/errors/not_found",
"did_you_mean": [
"new-checkout-flow"
],
"next_actions": [
{
"method": "GET",
"path": "/api/v1/orgs/acme/projects/checkout/flags"
}
]
}
X-RateLimit-Limit
integer

The maximum number of requests permitted per rate-limit window for this caller.

X-RateLimit-Remaining
integer

The number of requests remaining in the current rate-limit window.

X-RateLimit-Reset
integer

The UTC time at which the current rate-limit window resets, as a Unix timestamp in seconds.

Rate limit exceeded. Retry after the interval indicated by the Retry-After header.

Media type application/json

The frozen public-API error contract. error codes are stable snake_case strings. Wire keys are frozen snake_case too (error, message, docs_url, fields, retry_after) — the global camelCase naming policy would otherwise emit docsUrl/retryAfter, breaking the published spec. !:JsonPropertyName always wins over the policy, so these are pinned explicitly rather than relying on the property names already being lowercase for the single-word ones. did_you_mean, next_actions and connection_id are ADDITIVE optional keys (null → omitted via the global DefaultIgnoreCondition = WhenWritingNull), so pre-existing error bodies are byte-for-byte unchanged when they’re absent.

connection_id is present only on the sso_required error: the organization requires single sign-on, and this credential didn’t come through its identity provider. connection_id identifies which SSO connection to sign in with. plan_limit is present only on the plan_limit_reached error: which plan cap the request would have exceeded, so a client can branch on it without parsing message. change_freeze is present only on the change_frozen error (#4645): the change freeze that refused the write, so a client can show when it ends and whether the caller may break it, without parsing message.

object
error
required
string
message
required
string
docs_url
required
string
fields
object
key
additional properties
Array<string>
retry_after
integer format: int32
nullable
did_you_mean
Array<string>
nullable
next_actions
Array<object>
nullable
object
method
required
string
path
required
string
connection_id
string format: uuid
nullable
plan_limit

The cap behind a plan_limit_reached error. resource is the capped collection (projects, environments, flags, webhooks, members); plan is the plan’s wire name, as GET /api/v1/orgs/{org} returns it; max is the cap. The environment and flag caps are per project.

object
resource
required
string
plan
required
string
max
required
integer format: int32
change_freeze

The freeze behind a change_frozen error: id and name of the window, the environment’s environment_key, ends_at (UTC; always present, null for an open-ended window) and whether the caller’s role may break it (can_override, with X-Freeze-Override: true and an X-Intent-Reason).

object
id
required
string format: uuid
name
required
string
environment_key
required
string
ends_at
string format: date-time
nullable
can_override
required
boolean

Example

{
"error": "not_found",
"message": "Flag 'new-checkout-flw' was not found in project 'checkout'.",
"docs_url": "https://featureflip.io/docs/management-api/errors/not_found",
"did_you_mean": [
"new-checkout-flow"
],
"next_actions": [
{
"method": "GET",
"path": "/api/v1/orgs/acme/projects/checkout/flags"
}
]
}
Retry-After
integer

Number of seconds to wait before retrying the request.

X-RateLimit-Limit
integer

The maximum number of requests permitted per rate-limit window for this caller.

X-RateLimit-Remaining
integer

The number of requests remaining in the current rate-limit window.

X-RateLimit-Reset
integer

The UTC time at which the current rate-limit window resets, as a Unix timestamp in seconds.