Fix: OpenAPI spec does not document 429 responses (#7469) #7509

dsotirho-ucsc · 2025-10-21T17:16:35Z

Linked issues: #7469

Checklist

Author

¹ when the issue title describes a problem, the corresponding PR
title is Fix: followed by the issue title

Author (partiality)

Added p tag to titles of partial commits
This PR is labeled partial _{or completely resolves all linked issues}
This PR partially resolves each of the linked issues _{or does not have the partial label}

Author (reindex)

Added r tag to commit title _{or the changes introduced by this PR will not require reindexing of any deployment}
This PR is labeled reindex:dev _{or the changes introduced by it will not require reindexing of dev}
This PR is labeled reindex:anvildev _{or the changes introduced by it will not require reindexing of anvildev}
This PR is labeled reindex:anvilprod _{or the changes introduced by it will not require reindexing of anvilprod}
This PR is labeled reindex:prod _{or the changes introduced by it will not require reindexing of prod}
This PR is labeled reindex:partial and its description documents the specific reindexing procedure for dev, anvildev, anvilprod and prod _{or requires a full reindex or carries none of the labels reindex:dev, reindex:anvildev, reindex:anvilprod and reindex:prod}

Author (API changes)

This PR and its linked issues are labeled API _{or this PR does not modify a REST API}
Added a (A) tag to commit title for backwards (in)compatible changes _{or this PR does not modify a REST API}
Updated REST API version number in app.py _{or this PR does not modify a REST API}

Author (upgrading deployments)

Ran make docker_images.json and committed the resulting changes _{or this PR does not modify azul_docker_images, or any other variables referenced in the definition of that variable}
Documented upgrading of deployments in UPGRADING.rst _{or this PR does not require upgrading deployments}
Added u tag to commit title _{or this PR does not require upgrading deployments}
This PR is labeled upgrade _{or does not require upgrading deployments}
This PR is labeled deploy:shared _{or does not modify docker_images.json, and does not require deploying the shared component for any other reason}
This PR is labeled deploy:gitlab _{or does not require deploying the gitlab component}
This PR is labeled deploy:runner _{or does not require deploying the runner image}

Author (hotfixes)

Added F tag to main commit title _{or this PR does not include permanent fix for a temporary hotfix}
Reverted the temporary hotfixes for any linked issues _{or the none of the stable branches (anvilprod and prod) have temporary hotfixes for any of the issues linked to this PR}

Author (before every review)

Rebased PR branch on develop, squashed fixups from prior reviews
Ran make requirements_update _{or this PR does not modify Dockerfile, environment, requirements*.txt, common.mk, Makefile or environment.boot}
Added R tag to commit title _{or this PR does not modify requirements*.txt}
This PR is labeled reqs _{or does not modify requirements*.txt}
make integration_test passes in personal deployment _{or this PR does not modify functionality that could affect the IT outcome}
PR is awaiting requested review from a peer
Status of PR is Review requested
PR is assigned to only the peer and the author

Peer reviewer (after approval)

Note that after requesting changes, the PR must be assigned to only the author.

Actually approved the PR
PR is not a draft
PR is awaiting requested review from system administrator
Status of PR is Review requested
PR is assigned to only the system administrator and the author

System administrator (after approval)

Actually approved the PR
Labeled linked issues as demo or no demo
Commented on linked issues about demo expectations _{or all linked issues are labeled no demo}
Decided if PR can be labeled no sandbox
A comment to this PR details the completed security design review
PR title is appropriate as title of merge commit
N reviews label is accurate
Status of PR is Approved
PR is assigned to only the operator and the author

Operator

Checked reindex:… labels and r commit title tag
Checked that demo expectations are clear _{or all linked issues are labeled no demo}
Squashed PR branch and rebased onto develop
Sanity-checked history
Pushed PR branch to GitHub

Operator (deploy `.shared` and `.gitlab` components)

Ran _select dev.shared && CI_COMMIT_REF_NAME=develop make -C terraform/shared apply_keep_unused _{or this PR is not labeled deploy:shared}
Ran _select dev.gitlab && CI_COMMIT_REF_NAME=develop make -C terraform/gitlab apply _{or this PR is not labeled deploy:gitlab}
Ran _select anvildev.shared && CI_COMMIT_REF_NAME=develop make -C terraform/shared apply_keep_unused _{or this PR is not labeled deploy:shared}
Ran _select anvildev.gitlab && CI_COMMIT_REF_NAME=develop make -C terraform/gitlab apply _{or this PR is not labeled deploy:gitlab}
Checked the items in the next section _{or this PR is labeled deploy:gitlab}
PR is assigned to only the system administrator and the author _{or this PR is not labeled deploy:gitlab}

System administrator (post-deploy of `.gitlab` component)

Background migrations for dev.gitlab are complete _{or this PR is not labeled deploy:gitlab}
Background migrations for anvildev.gitlab are complete _{or this PR is not labeled deploy:gitlab}
PR is assigned to only the operator and the author

Operator (deploy runner image)

Ran _select dev.gitlab && make -C terraform/gitlab/runner _{or this PR is not labeled deploy:runner}
Ran _select anvildev.gitlab && make -C terraform/gitlab/runner _{or this PR is not labeled deploy:runner}

Operator (sandbox build)

Operator (merge the branch)

All status checks passed and the PR is mergeable
The title of the merge commit starts with the title of this PR
Added PR # reference to merge commit title
Collected commit title tags in merge commit title _{but only included p if the PR is also labeled partial}
Pushed merge commit to GitHub
Status of PR is Merged lower
Status of blocked issues is Triage _{or no issues are blocked on the linked issues}

Operator (main build)

Operator (reindex)

Operator (mirroring)

Started mirroring in dev _{or this PR does not require mirroring dev}
Started mirroring in anvildev _{or this PR does not require mirroring anvildev}
Checked for, triaged and possibly requeued messages in mirror fail queue in dev _{or this PR does not require mirroring dev}
Checked for, triaged and possibly requeued messages in mirror fail queue in anvildev _{or this PR does not require mirroring anvildev}
Emptied mirror fail queue in dev _{or this PR does not require mirroring dev}
Emptied mirror fail queue in anvildev _{or this PR does not require mirroring anvildev}

Operator

Propagated the deploy:shared, deploy:gitlab, deploy:runner, API, reindex:partial, reindex:anvilprod and reindex:prod labels to the next promotion PRs _{or this PR carries none of these labels}
Propagated any specific instructions related to the deploy:shared, deploy:gitlab, deploy:runner, API, reindex:partial, reindex:anvilprod and reindex:prod labels, from the description of this PR to that of the next promotion PRs _{or this PR carries none of these labels}
PR is assigned to no one

Shorthand for review comments

L line is too long
W line wrapping is wrong
Q bad quotes
F other formatting problem

coveralls · 2025-10-21T18:03:39Z

coverage: 85.414% (+0.007%) from 85.407%
when pulling 878af22 on issues/dsotirho-ucsc/7469-document-429-response
into a20581b on develop.

codecov · 2025-10-21T18:10:14Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 85.19%. Comparing base (a20581b) to head (878af22).

Additional details and impacted files

@@           Coverage Diff            @@
##           develop    #7509   +/-   ##
========================================
  Coverage    85.18%   85.19%           
========================================
  Files          156      156           
  Lines        22626    22644   +18     
========================================
+ Hits         19275    19292   +17     
- Misses        3351     3352    +1

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

dsotirho-ucsc · 2025-10-22T21:38:17Z

7509_IT_2025-10-22.txt

achave11-ucsc

Looks good so far, just eliminate the redundancy.

achave11-ucsc · 2025-10-23T22:39:21Z

src/azul/chalice.py

+            When handling this response, clients should wait the number of
+            seconds specified in the `Retry-After` header and then retry the
+            request.


Suggested change

When handling this response, clients should wait the number of

seconds specified in the `Retry-After` header and then retry the

request.

When handling this response, clients should honor the `Retry-After` header.

Implies the waiting to retry.

dsotirho-ucsc · 2025-10-24T22:54:50Z

7509_IT_2025-10-24.txt

achave11-ucsc

Approved ✅

achave11-ucsc · 2025-10-27T15:52:56Z

@dsotirho-ucsc, don't forget unassigning yourself when requesting review and only assigning the PR to the reviewer.

hannes-ucsc · 2025-10-27T22:40:55Z

src/azul/chalice.py

    def default_specs(self):
+        retry_after = format_description('''
+            When handling this response, clients should honor the `Retry-After`
+            header.


Suggested change

header.

header by waiting the specified number of second before retrying the request.

hannes-ucsc · 2025-10-27T22:43:09Z

test/test_openapi.py

-                    self.assertIn('Request timed out', description)
+                    for code, message in [
+                        ('429', 'Too many requests'),
+                        ('504', 'Request timed out'),


Suggested change

('504', 'Request timed out'),

('504', 'Gateway Timeout'),

I'm not sure about the capitalization. Be consistent with precedent in this module.

dsotirho-ucsc · 2025-11-19T19:46:02Z

7509_IT_2025-11-19.txt

hannes-ucsc · 2025-11-20T17:23:00Z

src/azul/collections.py

+
+    >>> deep_dict_merge.from_iterable([{0: 1}, {0: {2: 3}}, {0: {4: 5}}],
+    ...                               override=True)
+    {0: {2: 3, 4: 5}}


This contradicts the documentation, or is at least counterintuitive. I know why it happens, due to the accumulative nature of the implementation, but it is hard to explain. If the argument had {0: 1} in second place instead of first, the result would be {0: {4: 5}}. Let's disallow the mixed cases for now and update the documentation and tests accordingly. The only cases allowed are

All values are dicts, in which case override does not apply

No values are dicts, in which case the last value (not "later values") is used

PL, if this doesn't work for your use case.

dsotirho-ucsc · 2025-11-20T20:33:20Z

7509_IT_2025-11-20.txt

Reorder arguments

Add argument

…#7469)

dsotirho-ucsc self-assigned this Oct 21, 2025

dsotirho-ucsc linked an issue Oct 21, 2025 that may be closed by this pull request

OpenAPI spec does not document 429 responses #7469

Open

dsotirho-ucsc added the API API change affecting callers label Oct 21, 2025

dsotirho-ucsc force-pushed the issues/dsotirho-ucsc/7469-document-429-response branch 3 times, most recently from 1cab2a2 to 5d896f4 Compare October 21, 2025 17:54

dsotirho-ucsc force-pushed the issues/dsotirho-ucsc/7469-document-429-response branch 3 times, most recently from d0bd305 to 0960906 Compare October 22, 2025 17:43

dsotirho-ucsc requested a review from achave11-ucsc October 22, 2025 21:38

dsotirho-ucsc assigned achave11-ucsc and unassigned dsotirho-ucsc Oct 22, 2025

achave11-ucsc requested changes Oct 23, 2025

View reviewed changes

achave11-ucsc removed their assignment Oct 23, 2025

dsotirho-ucsc self-assigned this Oct 24, 2025

dsotirho-ucsc force-pushed the issues/dsotirho-ucsc/7469-document-429-response branch from 0960906 to 4c6509f Compare October 24, 2025 22:07

dsotirho-ucsc requested a review from achave11-ucsc October 24, 2025 22:54

dsotirho-ucsc assigned achave11-ucsc Oct 24, 2025

achave11-ucsc previously approved these changes Oct 27, 2025

View reviewed changes

achave11-ucsc assigned hannes-ucsc and unassigned achave11-ucsc and dsotirho-ucsc Oct 27, 2025

achave11-ucsc marked this pull request as ready for review October 27, 2025 15:53

achave11-ucsc requested a review from hannes-ucsc as a code owner October 27, 2025 15:53

hannes-ucsc requested changes Oct 27, 2025

View reviewed changes

hannes-ucsc added 3 reviews [process] Lead requested changes thrice and removed 2 reviews [process] Lead requested changes twice labels Nov 18, 2025

hannes-ucsc removed their assignment Nov 18, 2025

dsotirho-ucsc force-pushed the issues/dsotirho-ucsc/7469-document-429-response branch 2 times, most recently from 82a9c13 to 18d20f8 Compare November 19, 2025 18:24

dsotirho-ucsc assigned hannes-ucsc Nov 19, 2025

hannes-ucsc requested changes Nov 20, 2025

View reviewed changes

hannes-ucsc removed their assignment Nov 20, 2025

dsotirho-ucsc mentioned this pull request Nov 20, 2025

Don't retry on 500 errors DataBiosphere/data-browser#4561

Open

dsotirho-ucsc force-pushed the issues/dsotirho-ucsc/7469-document-429-response branch from 18d20f8 to 878af22 Compare November 20, 2025 19:07

dsotirho-ucsc requested a review from hannes-ucsc November 20, 2025 20:33

dsotirho-ucsc assigned hannes-ucsc Nov 20, 2025

dsotirho-ucsc and others added 15 commits November 21, 2025 00:15

Add override parameter to deep_dict_merge

1acd884

[1/2] Use override when merging spec with spec defaults

4810e43

Reorder arguments

[2/2] Use override when merging spec with spec defaults

22cab29

Add argument

Add a Retry-After header to 503 responses from Azul (#7469)

e231160

Add a Retry-After header to 429 responses from API Gateway (#7469)

8a9cf34

[a] Remove the Retry-After header from 504 responses from API Gateway (…

29a9584

…#7469)

[a] Add default response types to OpenAPI spec (#7469)

2b23cc2

drop! Add endpoint to return a 503 response

1238630

Protect method

167de5c

Don't duplicate field initialization

dc51b33

Avoid redundant calls to isinstance

00d8745

Fix docstring contradicting type hint

912a039

Document from_iterable last

12cf572

Interleave documentation and doctests to eliminate repetitions

cd263f8

Tweak exception messages

1bc704f

hannes-ucsc force-pushed the issues/dsotirho-ucsc/7469-document-429-response branch from 878af22 to 1bc704f Compare November 21, 2025 08:27

	header.
	header by waiting the specified number of second before retrying the request.

Fix: OpenAPI spec does not document 429 responses (#7469) #7509

Are you sure you want to change the base?

Fix: OpenAPI spec does not document 429 responses (#7469) #7509

Conversation

dsotirho-ucsc commented Oct 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Checklist

Author

Author (partiality)

Author (reindex)

Author (API changes)

Author (upgrading deployments)

Author (hotfixes)

Author (before every review)

Peer reviewer (after approval)

System administrator (after approval)

Operator

Operator (deploy .shared and .gitlab components)

System administrator (post-deploy of .gitlab component)

Operator (deploy runner image)

Operator (sandbox build)

Operator (merge the branch)

Operator (main build)

Operator (reindex)

Operator (mirroring)

Operator

Shorthand for review comments

Uh oh!

coveralls commented Oct 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov bot commented Oct 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

dsotirho-ucsc commented Oct 22, 2025

Uh oh!

achave11-ucsc left a comment

Choose a reason for hiding this comment

Uh oh!

achave11-ucsc Oct 23, 2025

Choose a reason for hiding this comment

Uh oh!

dsotirho-ucsc commented Oct 24, 2025

Uh oh!

achave11-ucsc left a comment

Choose a reason for hiding this comment

Uh oh!

achave11-ucsc commented Oct 27, 2025

Uh oh!

hannes-ucsc Oct 27, 2025

Choose a reason for hiding this comment

Uh oh!

hannes-ucsc Oct 27, 2025

Choose a reason for hiding this comment

Uh oh!

hannes-ucsc Oct 27, 2025

Choose a reason for hiding this comment

Uh oh!

dsotirho-ucsc commented Nov 19, 2025

Uh oh!

hannes-ucsc Nov 20, 2025

Choose a reason for hiding this comment

Uh oh!

dsotirho-ucsc commented Nov 20, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

dsotirho-ucsc commented Oct 21, 2025 •

edited

Loading

Operator (deploy `.shared` and `.gitlab` components)

System administrator (post-deploy of `.gitlab` component)

coveralls commented Oct 21, 2025 •

edited

Loading

codecov bot commented Oct 21, 2025 •

edited

Loading