Document HTTP statuses that API routes raise but never declared

[ColtenOuO]

Follow-up to #67570, #67571 and #70992, which each fixed one instance of the same
drift: a handler raises an HTTP status that create_openapi_http_exception_doc(...)
never declares, so the generated spec — and every client built from it — has no model
for a response the API really returns.

Endpoint	Undeclared	Reached when
POST /backfills/dry_run	400	the Dag's allowed_run_types excludes backfill
DELETE /dags/{dag_id}/dagRuns/{dag_run_id}	409	the run's state is not in DagRunMutableStates
GET /dags/{dag_id}/dagRuns	400	a partition_date filter with dag_id=~, or against a non-partitioned Dag
DELETE /dags/{dag_id}	409	task instances are still running
PATCH /hitlDetails/{dag_id}/{dag_run_id}/{task_id}	400	chosen_options outside options, or several sent to a non-multiple detail
POST /dags/{dag_id}/clearTaskInstances	400	past/future with a run that has no logical date
GET /ui/dags/{dag_id}/latest_run	400	dag_id=~
GET /ui/dependencies	400	dependency_type=data with a missing or non-numeric asset: node id

Each is driven by request input or by persisted state, so each is really returned today.

ui/dependencies.py also had one bare raise HTTPException(404, ...); it now uses
status.HTTP_404_NOT_FOUND, the same tidy-up as #67571.

xcom.py is deliberately left out — it is fixed in #70992.

Behaviour

Otherwise unchanged: only responses= declarations, so the regenerated spec and UI
client are additive (6 additions to the public spec, 2 to _private_ui.yaml, no
deletions). No new tests — the statuses were already produced and are already covered.

---

Was generative AI tooling used to co-author this PR?

• Yes — Claude Code (Opus 5)

[bbovenzi]

What does 404 on a POST variable endpoint mean?

[ColtenOuO]

Sorry about that.

It doesn't mean anything on a create endpoint.

I found these with a script that compares the statuses each handler raises against the ones its create_openapi_http_exception_doc(...) declares, so the list is everything that had drifted. What I didn't check was whether each raise can actually fire, and this one can't.

I've removed the branch. If the read-back ever did come back empty, response validation now gives a 500, which is the right answer for a write that silently didn't happen.

The description is updated too: that row is gone, and the table now says when each of the remaining statuses is returned.

Thanks for your review!

[jason810496]

Nice! Thanks for adding the missing status code.

I found these with a script that compares the statuses each handler raises against the ones its create_openapi_http_exception_doc(...) declares, so the list is everything that had drifted.

I prefer to introduce the script you mentioned as pre-commit (prek) hook static check (please take the dev/script as referece) that ensure all the status code that might raise within the route are documented in the router definition level to prevent the further drift from happening again instead of one-time manual fix.

Which means we might need to walk into the module level (e.g. the exception might be raise within the common function that we imported at router level).

[ColtenOuO]

Thanks again!

Reverted the post_variable change.

This PR now only adds responses= declarations and doesn't touch any route implementation.

[ColtenOuO]

rebase to lastest upstream/main and re-run the CI.

[pierrejeambrun]

Thanks for the PR, LGTM.

[github-actions]

Backport successfully created: v3-3-test

Note: As of Merging PRs targeted for Airflow 3.X
the committer who merges the PR is responsible for backporting the PRs that are bug fixes (generally speaking) to the maintenance branches.

In matter of doubt please ask in #release-management Slack channel.

Status	Branch	Result
✅	v3-3-test

[ColtenOuO]

Follow-up to #67570, #67571 and #70992, which each fixed one instance of the same
drift: a handler raises an HTTP status that create_openapi_http_exception_doc(...)
never declares, so the generated spec — and every client built from it — has no model
for a response the API really returns.

Endpoint	Undeclared	Reached when
POST /backfills/dry_run	400	the Dag's allowed_run_types excludes backfill
DELETE /dags/{dag_id}/dagRuns/{dag_run_id}	409	the run's state is not in DagRunMutableStates
GET /dags/{dag_id}/dagRuns	400	a partition_date filter with dag_id=~, or against a non-partitioned Dag
DELETE /dags/{dag_id}	409	task instances are still running
PATCH /hitlDetails/{dag_id}/{dag_run_id}/{task_id}	400	chosen_options outside options, or several sent to a non-multiple detail
POST /dags/{dag_id}/clearTaskInstances	400	past/future with a run that has no logical date
GET /ui/dags/{dag_id}/latest_run	400	dag_id=~
GET /ui/dependencies	400	dependency_type=data with a missing or non-numeric asset: node id

Each is driven by request input or by persisted state, so each is really returned today.

ui/dependencies.py also had one bare raise HTTPException(404, ...); it now uses
status.HTTP_404_NOT_FOUND, the same tidy-up as #67571.

xcom.py is deliberately left out — it is fixed in #70992.

Behaviour

Otherwise unchanged: only responses= declarations, so the regenerated spec and UI
client are additive (6 additions to the public spec, 2 to _private_ui.yaml, no
deletions). No new tests — the statuses were already produced and are already covered.

---

Was generative AI tooling used to co-author this PR?

• Yes — Claude Code (Opus 5)

[bbovenzi]

What does 404 on a POST variable endpoint mean?

[ColtenOuO]

Sorry about that.

It doesn't mean anything on a create endpoint.

I found these with a script that compares the statuses each handler raises against the ones its create_openapi_http_exception_doc(...) declares, so the list is everything that had drifted. What I didn't check was whether each raise can actually fire, and this one can't.

I've removed the branch. If the read-back ever did come back empty, response validation now gives a 500, which is the right answer for a write that silently didn't happen.

The description is updated too: that row is gone, and the table now says when each of the remaining statuses is returned.

Thanks for your review!

[jason810496]

Nice! Thanks for adding the missing status code.

I found these with a script that compares the statuses each handler raises against the ones its create_openapi_http_exception_doc(...) declares, so the list is everything that had drifted.

I prefer to introduce the script you mentioned as pre-commit (prek) hook static check (please take the dev/script as referece) that ensure all the status code that might raise within the route are documented in the router definition level to prevent the further drift from happening again instead of one-time manual fix.

Which means we might need to walk into the module level (e.g. the exception might be raise within the common function that we imported at router level).

[ColtenOuO]

Thanks again!

Reverted the post_variable change.

This PR now only adds responses= declarations and doesn't touch any route implementation.

[ColtenOuO]

rebase to lastest upstream/main and re-run the CI.

[pierrejeambrun]

Thanks for the PR, LGTM.

[github-actions]

Backport successfully created: v3-3-test

Note: As of Merging PRs targeted for Airflow 3.X
the committer who merges the PR is responsible for backporting the PRs that are bug fixes (generally speaking) to the maintenance branches.

In matter of doubt please ask in #release-management Slack channel.

Status	Branch	Result
✅	v3-3-test

[ColtenOuO]

Follow-up to #67570, #67571 and #70992, which each fixed one instance of the same
drift: a handler raises an HTTP status that create_openapi_http_exception_doc(...)
never declares, so the generated spec — and every client built from it — has no model
for a response the API really returns.

Endpoint	Undeclared	Reached when
POST /backfills/dry_run	400	the Dag's allowed_run_types excludes backfill
DELETE /dags/{dag_id}/dagRuns/{dag_run_id}	409	the run's state is not in DagRunMutableStates
GET /dags/{dag_id}/dagRuns	400	a partition_date filter with dag_id=~, or against a non-partitioned Dag
DELETE /dags/{dag_id}	409	task instances are still running
PATCH /hitlDetails/{dag_id}/{dag_run_id}/{task_id}	400	chosen_options outside options, or several sent to a non-multiple detail
POST /dags/{dag_id}/clearTaskInstances	400	past/future with a run that has no logical date
GET /ui/dags/{dag_id}/latest_run	400	dag_id=~
GET /ui/dependencies	400	dependency_type=data with a missing or non-numeric asset: node id

Each is driven by request input or by persisted state, so each is really returned today.

ui/dependencies.py also had one bare raise HTTPException(404, ...); it now uses
status.HTTP_404_NOT_FOUND, the same tidy-up as #67571.

xcom.py is deliberately left out — it is fixed in #70992.

Behaviour

Otherwise unchanged: only responses= declarations, so the regenerated spec and UI
client are additive (6 additions to the public spec, 2 to _private_ui.yaml, no
deletions). No new tests — the statuses were already produced and are already covered.

---

Was generative AI tooling used to co-author this PR?

• Yes — Claude Code (Opus 5)

[bbovenzi]

What does 404 on a POST variable endpoint mean?

[ColtenOuO]

Sorry about that.

It doesn't mean anything on a create endpoint.

I found these with a script that compares the statuses each handler raises against the ones its create_openapi_http_exception_doc(...) declares, so the list is everything that had drifted. What I didn't check was whether each raise can actually fire, and this one can't.

I've removed the branch. If the read-back ever did come back empty, response validation now gives a 500, which is the right answer for a write that silently didn't happen.

The description is updated too: that row is gone, and the table now says when each of the remaining statuses is returned.

Thanks for your review!

[jason810496]

Nice! Thanks for adding the missing status code.

I found these with a script that compares the statuses each handler raises against the ones its create_openapi_http_exception_doc(...) declares, so the list is everything that had drifted.

I prefer to introduce the script you mentioned as pre-commit (prek) hook static check (please take the dev/script as referece) that ensure all the status code that might raise within the route are documented in the router definition level to prevent the further drift from happening again instead of one-time manual fix.

Which means we might need to walk into the module level (e.g. the exception might be raise within the common function that we imported at router level).

[ColtenOuO]

Thanks again!

Reverted the post_variable change.

This PR now only adds responses= declarations and doesn't touch any route implementation.

[ColtenOuO]

rebase to lastest upstream/main and re-run the CI.

[pierrejeambrun]

Thanks for the PR, LGTM.

[github-actions]

Backport successfully created: v3-3-test

Note: As of Merging PRs targeted for Airflow 3.X
the committer who merges the PR is responsible for backporting the PRs that are bug fixes (generally speaking) to the maintenance branches.

In matter of doubt please ask in #release-management Slack channel.

Status	Branch	Result
✅	v3-3-test

[ColtenOuO]

Follow-up to #67570, #67571 and #70992, which each fixed one instance of the same
drift: a handler raises an HTTP status that create_openapi_http_exception_doc(...)
never declares, so the generated spec — and every client built from it — has no model
for a response the API really returns.

Endpoint	Undeclared	Reached when
POST /backfills/dry_run	400	the Dag's allowed_run_types excludes backfill
DELETE /dags/{dag_id}/dagRuns/{dag_run_id}	409	the run's state is not in DagRunMutableStates
GET /dags/{dag_id}/dagRuns	400	a partition_date filter with dag_id=~, or against a non-partitioned Dag
DELETE /dags/{dag_id}	409	task instances are still running
PATCH /hitlDetails/{dag_id}/{dag_run_id}/{task_id}	400	chosen_options outside options, or several sent to a non-multiple detail
POST /dags/{dag_id}/clearTaskInstances	400	past/future with a run that has no logical date
GET /ui/dags/{dag_id}/latest_run	400	dag_id=~
GET /ui/dependencies	400	dependency_type=data with a missing or non-numeric asset: node id

Each is driven by request input or by persisted state, so each is really returned today.

ui/dependencies.py also had one bare raise HTTPException(404, ...); it now uses
status.HTTP_404_NOT_FOUND, the same tidy-up as #67571.

xcom.py is deliberately left out — it is fixed in #70992.

Behaviour

Otherwise unchanged: only responses= declarations, so the regenerated spec and UI
client are additive (6 additions to the public spec, 2 to _private_ui.yaml, no
deletions). No new tests — the statuses were already produced and are already covered.

---

Was generative AI tooling used to co-author this PR?

• Yes — Claude Code (Opus 5)

[bbovenzi]

What does 404 on a POST variable endpoint mean?

[ColtenOuO]

Sorry about that.

It doesn't mean anything on a create endpoint.

I found these with a script that compares the statuses each handler raises against the ones its create_openapi_http_exception_doc(...) declares, so the list is everything that had drifted. What I didn't check was whether each raise can actually fire, and this one can't.

I've removed the branch. If the read-back ever did come back empty, response validation now gives a 500, which is the right answer for a write that silently didn't happen.

The description is updated too: that row is gone, and the table now says when each of the remaining statuses is returned.

Thanks for your review!

[jason810496]

Nice! Thanks for adding the missing status code.

I found these with a script that compares the statuses each handler raises against the ones its create_openapi_http_exception_doc(...) declares, so the list is everything that had drifted.

I prefer to introduce the script you mentioned as pre-commit (prek) hook static check (please take the dev/script as referece) that ensure all the status code that might raise within the route are documented in the router definition level to prevent the further drift from happening again instead of one-time manual fix.

Which means we might need to walk into the module level (e.g. the exception might be raise within the common function that we imported at router level).

[ColtenOuO]

Thanks again!

Reverted the post_variable change.

This PR now only adds responses= declarations and doesn't touch any route implementation.

[ColtenOuO]

rebase to lastest upstream/main and re-run the CI.

[pierrejeambrun]

Thanks for the PR, LGTM.

[github-actions]

Backport successfully created: v3-3-test

Note: As of Merging PRs targeted for Airflow 3.X
the committer who merges the PR is responsible for backporting the PRs that are bug fixes (generally speaking) to the maintenance branches.

In matter of doubt please ask in #release-management Slack channel.

Status	Branch	Result
✅	v3-3-test

[ColtenOuO]

Follow-up to #67570, #67571 and #70992, which each fixed one instance of the same
drift: a handler raises an HTTP status that create_openapi_http_exception_doc(...)
never declares, so the generated spec — and every client built from it — has no model
for a response the API really returns.

Endpoint	Undeclared	Reached when
POST /backfills/dry_run	400	the Dag's allowed_run_types excludes backfill
DELETE /dags/{dag_id}/dagRuns/{dag_run_id}	409	the run's state is not in DagRunMutableStates
GET /dags/{dag_id}/dagRuns	400	a partition_date filter with dag_id=~, or against a non-partitioned Dag
DELETE /dags/{dag_id}	409	task instances are still running
PATCH /hitlDetails/{dag_id}/{dag_run_id}/{task_id}	400	chosen_options outside options, or several sent to a non-multiple detail
POST /dags/{dag_id}/clearTaskInstances	400	past/future with a run that has no logical date
GET /ui/dags/{dag_id}/latest_run	400	dag_id=~
GET /ui/dependencies	400	dependency_type=data with a missing or non-numeric asset: node id

Each is driven by request input or by persisted state, so each is really returned today.

ui/dependencies.py also had one bare raise HTTPException(404, ...); it now uses
status.HTTP_404_NOT_FOUND, the same tidy-up as #67571.

xcom.py is deliberately left out — it is fixed in #70992.

Behaviour

Otherwise unchanged: only responses= declarations, so the regenerated spec and UI
client are additive (6 additions to the public spec, 2 to _private_ui.yaml, no
deletions). No new tests — the statuses were already produced and are already covered.

---

Was generative AI tooling used to co-author this PR?

• Yes — Claude Code (Opus 5)

[bbovenzi]

What does 404 on a POST variable endpoint mean?

[ColtenOuO]

Sorry about that.

It doesn't mean anything on a create endpoint.

I found these with a script that compares the statuses each handler raises against the ones its create_openapi_http_exception_doc(...) declares, so the list is everything that had drifted. What I didn't check was whether each raise can actually fire, and this one can't.

I've removed the branch. If the read-back ever did come back empty, response validation now gives a 500, which is the right answer for a write that silently didn't happen.

The description is updated too: that row is gone, and the table now says when each of the remaining statuses is returned.

Thanks for your review!

[jason810496]

Nice! Thanks for adding the missing status code.

I found these with a script that compares the statuses each handler raises against the ones its create_openapi_http_exception_doc(...) declares, so the list is everything that had drifted.

I prefer to introduce the script you mentioned as pre-commit (prek) hook static check (please take the dev/script as referece) that ensure all the status code that might raise within the route are documented in the router definition level to prevent the further drift from happening again instead of one-time manual fix.

Which means we might need to walk into the module level (e.g. the exception might be raise within the common function that we imported at router level).

[ColtenOuO]

Thanks again!

Reverted the post_variable change.

This PR now only adds responses= declarations and doesn't touch any route implementation.

[ColtenOuO]

rebase to lastest upstream/main and re-run the CI.

[pierrejeambrun]

Thanks for the PR, LGTM.

[github-actions]

Backport successfully created: v3-3-test

Note: As of Merging PRs targeted for Airflow 3.X
the committer who merges the PR is responsible for backporting the PRs that are bug fixes (generally speaking) to the maintenance branches.

In matter of doubt please ask in #release-management Slack channel.

Status	Branch	Result
✅	v3-3-test

[ColtenOuO]

Follow-up to #67570, #67571 and #70992, which each fixed one instance of the same
drift: a handler raises an HTTP status that create_openapi_http_exception_doc(...)
never declares, so the generated spec — and every client built from it — has no model
for a response the API really returns.

Endpoint	Undeclared	Reached when
POST /backfills/dry_run	400	the Dag's allowed_run_types excludes backfill
DELETE /dags/{dag_id}/dagRuns/{dag_run_id}	409	the run's state is not in DagRunMutableStates
GET /dags/{dag_id}/dagRuns	400	a partition_date filter with dag_id=~, or against a non-partitioned Dag
DELETE /dags/{dag_id}	409	task instances are still running
PATCH /hitlDetails/{dag_id}/{dag_run_id}/{task_id}	400	chosen_options outside options, or several sent to a non-multiple detail
POST /dags/{dag_id}/clearTaskInstances	400	past/future with a run that has no logical date
GET /ui/dags/{dag_id}/latest_run	400	dag_id=~
GET /ui/dependencies	400	dependency_type=data with a missing or non-numeric asset: node id

Each is driven by request input or by persisted state, so each is really returned today.

ui/dependencies.py also had one bare raise HTTPException(404, ...); it now uses
status.HTTP_404_NOT_FOUND, the same tidy-up as #67571.

xcom.py is deliberately left out — it is fixed in #70992.

Behaviour

Otherwise unchanged: only responses= declarations, so the regenerated spec and UI
client are additive (6 additions to the public spec, 2 to _private_ui.yaml, no
deletions). No new tests — the statuses were already produced and are already covered.

---

Was generative AI tooling used to co-author this PR?

• Yes — Claude Code (Opus 5)

[bbovenzi]

What does 404 on a POST variable endpoint mean?

[ColtenOuO]

Sorry about that.

It doesn't mean anything on a create endpoint.

I found these with a script that compares the statuses each handler raises against the ones its create_openapi_http_exception_doc(...) declares, so the list is everything that had drifted. What I didn't check was whether each raise can actually fire, and this one can't.

I've removed the branch. If the read-back ever did come back empty, response validation now gives a 500, which is the right answer for a write that silently didn't happen.

The description is updated too: that row is gone, and the table now says when each of the remaining statuses is returned.

Thanks for your review!

[jason810496]

Nice! Thanks for adding the missing status code.

I found these with a script that compares the statuses each handler raises against the ones its create_openapi_http_exception_doc(...) declares, so the list is everything that had drifted.

I prefer to introduce the script you mentioned as pre-commit (prek) hook static check (please take the dev/script as referece) that ensure all the status code that might raise within the route are documented in the router definition level to prevent the further drift from happening again instead of one-time manual fix.

Which means we might need to walk into the module level (e.g. the exception might be raise within the common function that we imported at router level).

[ColtenOuO]

Thanks again!

Reverted the post_variable change.

This PR now only adds responses= declarations and doesn't touch any route implementation.

[ColtenOuO]

rebase to lastest upstream/main and re-run the CI.

[pierrejeambrun]

Thanks for the PR, LGTM.

[github-actions]

Backport successfully created: v3-3-test

Note: As of Merging PRs targeted for Airflow 3.X
the committer who merges the PR is responsible for backporting the PRs that are bug fixes (generally speaking) to the maintenance branches.

In matter of doubt please ask in #release-management Slack channel.

Status	Branch	Result
✅	v3-3-test

[ColtenOuO]

Follow-up to #67570, #67571 and #70992, which each fixed one instance of the same
drift: a handler raises an HTTP status that create_openapi_http_exception_doc(...)
never declares, so the generated spec — and every client built from it — has no model
for a response the API really returns.

Endpoint	Undeclared	Reached when
POST /backfills/dry_run	400	the Dag's allowed_run_types excludes backfill
DELETE /dags/{dag_id}/dagRuns/{dag_run_id}	409	the run's state is not in DagRunMutableStates
GET /dags/{dag_id}/dagRuns	400	a partition_date filter with dag_id=~, or against a non-partitioned Dag
DELETE /dags/{dag_id}	409	task instances are still running
PATCH /hitlDetails/{dag_id}/{dag_run_id}/{task_id}	400	chosen_options outside options, or several sent to a non-multiple detail
POST /dags/{dag_id}/clearTaskInstances	400	past/future with a run that has no logical date
GET /ui/dags/{dag_id}/latest_run	400	dag_id=~
GET /ui/dependencies	400	dependency_type=data with a missing or non-numeric asset: node id

Each is driven by request input or by persisted state, so each is really returned today.

ui/dependencies.py also had one bare raise HTTPException(404, ...); it now uses
status.HTTP_404_NOT_FOUND, the same tidy-up as #67571.

xcom.py is deliberately left out — it is fixed in #70992.

Behaviour

Otherwise unchanged: only responses= declarations, so the regenerated spec and UI
client are additive (6 additions to the public spec, 2 to _private_ui.yaml, no
deletions). No new tests — the statuses were already produced and are already covered.

---

Was generative AI tooling used to co-author this PR?

• Yes — Claude Code (Opus 5)

[bbovenzi]

What does 404 on a POST variable endpoint mean?

[ColtenOuO]

Sorry about that.

It doesn't mean anything on a create endpoint.

I found these with a script that compares the statuses each handler raises against the ones its create_openapi_http_exception_doc(...) declares, so the list is everything that had drifted. What I didn't check was whether each raise can actually fire, and this one can't.

I've removed the branch. If the read-back ever did come back empty, response validation now gives a 500, which is the right answer for a write that silently didn't happen.

The description is updated too: that row is gone, and the table now says when each of the remaining statuses is returned.

Thanks for your review!

[jason810496]

Nice! Thanks for adding the missing status code.

I found these with a script that compares the statuses each handler raises against the ones its create_openapi_http_exception_doc(...) declares, so the list is everything that had drifted.

I prefer to introduce the script you mentioned as pre-commit (prek) hook static check (please take the dev/script as referece) that ensure all the status code that might raise within the route are documented in the router definition level to prevent the further drift from happening again instead of one-time manual fix.

Which means we might need to walk into the module level (e.g. the exception might be raise within the common function that we imported at router level).

[ColtenOuO]

Thanks again!

Reverted the post_variable change.

This PR now only adds responses= declarations and doesn't touch any route implementation.

[ColtenOuO]

rebase to lastest upstream/main and re-run the CI.

[pierrejeambrun]

Thanks for the PR, LGTM.

[github-actions]

Backport successfully created: v3-3-test

Note: As of Merging PRs targeted for Airflow 3.X
the committer who merges the PR is responsible for backporting the PRs that are bug fixes (generally speaking) to the maintenance branches.

In matter of doubt please ask in #release-management Slack channel.

Status	Branch	Result
✅	v3-3-test

[ColtenOuO]

Follow-up to #67570, #67571 and #70992, which each fixed one instance of the same
drift: a handler raises an HTTP status that create_openapi_http_exception_doc(...)
never declares, so the generated spec — and every client built from it — has no model
for a response the API really returns.

Endpoint	Undeclared	Reached when
POST /backfills/dry_run	400	the Dag's allowed_run_types excludes backfill
DELETE /dags/{dag_id}/dagRuns/{dag_run_id}	409	the run's state is not in DagRunMutableStates
GET /dags/{dag_id}/dagRuns	400	a partition_date filter with dag_id=~, or against a non-partitioned Dag
DELETE /dags/{dag_id}	409	task instances are still running
PATCH /hitlDetails/{dag_id}/{dag_run_id}/{task_id}	400	chosen_options outside options, or several sent to a non-multiple detail
POST /dags/{dag_id}/clearTaskInstances	400	past/future with a run that has no logical date
GET /ui/dags/{dag_id}/latest_run	400	dag_id=~
GET /ui/dependencies	400	dependency_type=data with a missing or non-numeric asset: node id

Each is driven by request input or by persisted state, so each is really returned today.

ui/dependencies.py also had one bare raise HTTPException(404, ...); it now uses
status.HTTP_404_NOT_FOUND, the same tidy-up as #67571.

xcom.py is deliberately left out — it is fixed in #70992.

Behaviour

Otherwise unchanged: only responses= declarations, so the regenerated spec and UI
client are additive (6 additions to the public spec, 2 to _private_ui.yaml, no
deletions). No new tests — the statuses were already produced and are already covered.

---

Was generative AI tooling used to co-author this PR?

• Yes — Claude Code (Opus 5)

[bbovenzi]

What does 404 on a POST variable endpoint mean?

[ColtenOuO]

Sorry about that.

It doesn't mean anything on a create endpoint.

I found these with a script that compares the statuses each handler raises against the ones its create_openapi_http_exception_doc(...) declares, so the list is everything that had drifted. What I didn't check was whether each raise can actually fire, and this one can't.

I've removed the branch. If the read-back ever did come back empty, response validation now gives a 500, which is the right answer for a write that silently didn't happen.

The description is updated too: that row is gone, and the table now says when each of the remaining statuses is returned.

Thanks for your review!

[jason810496]

Nice! Thanks for adding the missing status code.

I found these with a script that compares the statuses each handler raises against the ones its create_openapi_http_exception_doc(...) declares, so the list is everything that had drifted.

I prefer to introduce the script you mentioned as pre-commit (prek) hook static check (please take the dev/script as referece) that ensure all the status code that might raise within the route are documented in the router definition level to prevent the further drift from happening again instead of one-time manual fix.

Which means we might need to walk into the module level (e.g. the exception might be raise within the common function that we imported at router level).

[ColtenOuO]

Thanks again!

Reverted the post_variable change.

This PR now only adds responses= declarations and doesn't touch any route implementation.

[ColtenOuO]

rebase to lastest upstream/main and re-run the CI.

[pierrejeambrun]

Thanks for the PR, LGTM.

[github-actions]

Backport successfully created: v3-3-test

Note: As of Merging PRs targeted for Airflow 3.X
the committer who merges the PR is responsible for backporting the PRs that are bug fixes (generally speaking) to the maintenance branches.

In matter of doubt please ask in #release-management Slack channel.

Status	Branch	Result
✅	v3-3-test