docs: document HTTP 409 response for policy-blocked promote/rollback#13
Merged
Merged
Conversation
The fix(server) commit (b4f2f6a) changed POST /v1/promote and POST /v1/rollback to return HTTP 409 Conflict when the active policy blocks the action, replacing the prior behavior of HTTP 200 with promoted_pointer_changed=false. Update three reference docs to reflect this: - docs/http-api.md: add a 'Policy-blocked response (HTTP 409)' section under POST /v1/promote with the exact JSON shape, update the error table to include 409, and mirror the equivalent note for POST /v1/rollback. - docs/operations-and-policy.md: expand the 'Promotion blocked by policy' section to call out the 409 for HTTP and the raised HTTPStatusError for the SDK, replacing the single sentence that only mentioned CLI and HTTP 200 behavior. - docs/sdk.md: add a 'Policy-blocked promote/rollback (HTTP 409)' subsection under Error handling with a code example showing how to catch and inspect the 409 detail body. Co-authored-by: Gottam Sai Bharath <Gsbreddy@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Docs added/updated
docs/http-api.mdPOST /v1/promote: Added a "Policy-blocked response (HTTP 409)" section with the exact JSON shape (detail.message,detail.outcomeincludingpromoted_pointer_changed: falseandpolicy.reasons). Updated the errors table to include HTTP 409.POST /v1/rollback: Added an equivalent note that policy-blocked rollbacks return the same 409 shape with"Rollback blocked by policy."as the message.docs/operations-and-policy.mdhttpx.HTTPStatusErrorwithstatus_code == 409).docs/sdk.mddetail["message"]anddetail["outcome"]["policy"]["reasons"], and notes that the blocked action is still recorded in the audit ledger.Codepaths covered
src/flightdeck/server/routes/actions.py—_raise_policy_blocked(new helper) and the updatedpost_promote/post_rollbackroute handlers that now raise HTTP 409 instead of returning HTTP 200 withpromoted_pointer_changed: false.Knowledge gaps addressed
The
fix(server)commit (b4f2f6a) introduced a breaking behavior change: policy-blocked actions now return HTTP 409 instead of HTTP 200. All three reference docs still described the old HTTP 200 path. This PR brings them into sync so API consumers, SDK users, and operations engineers see the correct status codes and error shapes.