Split NCBI outages from paper-level text-unavailable in PmcBiocFetcher - #311
Merged
Conversation
Prompted by a real incident: the whole /research/bionlp/RESTful/* tree returned 503 "no healthy upstream" for hours while the rest of NCBI was fine, but we reported it to users as "this article has no full text" and PmcBiocFetcher logged nothing at all, so the outage was invisible server-side. Transport failures / 5xx / 429 now raise UpstreamUnavailableException -> terminal upstream-unavailable (not cached, not publishable), kept distinct from text-unavailable since the two call for opposite user actions. Added log4j logging (error/warn/info per outcome, including the response body snippet that identified this as NCBI's problem) and a javadoc note on BIOC_URL_BASE recording the PubTator3 endpoint as a verified fallback source. Replaced the unused HttpClient constructor seam with a narrow BiocHttpExchange interface so every branch of the failure taxonomy is unit-testable without network. Front-end companion change (new upstream-unavailable status, messaging, recovery buttons) lives in the web-monorepo repo and ships together.
bobular
commented
Aug 10, 2026
bobular
left a comment
Member
Author
There was a problem hiding this comment.
Reviewed/understood all the Claude code and tested on my dev site. Log message (wdk.log) for the current problem looks like this:
ERROR - org.apidb.apicommon.service.services.ai.article.PmcBiocFetcher:158 - PMC BioC returned HTTP 503 for PMID 21533217 [https://www.ncbi.nlm.nih.gov/research/bionlp/RESTful/pmcoa.cgi/BioC_json/21533217] after 59 ms; treating as upstream outage. Body: no healthy upstream
Client devtools shows this:
{
"reason": "the PMC BioC service returned HTTP 503 for PMID 21533217",
"job_id": "2077e3900a195b7a95d40a38a22a91cc6acd527731e1d1467e9fd412630a53a3",
"type": "upstream-unavailable"
}
Client browser shows message in main PR description screenshot.
ryanrdoherty
approved these changes
Aug 17, 2026
bobular
added a commit
that referenced
this pull request
Aug 17, 2026
#311) Prompted by a real incident: the whole /research/bionlp/RESTful/* tree returned 503 "no healthy upstream" for hours while the rest of NCBI was fine, but we reported it to users as "this article has no full text" and PmcBiocFetcher logged nothing at all, so the outage was invisible server-side. Transport failures / 5xx / 429 now raise UpstreamUnavailableException -> terminal upstream-unavailable (not cached, not publishable), kept distinct from text-unavailable since the two call for opposite user actions. Added log4j logging (error/warn/info per outcome, including the response body snippet that identified this as NCBI's problem) and a javadoc note on BIOC_URL_BASE recording the PubTator3 endpoint as a verified fallback source. Replaced the unused HttpClient constructor seam with a narrow BiocHttpExchange interface so every branch of the failure taxonomy is unit-testable without network. Front-end companion change (new upstream-unavailable status, messaging, recovery buttons) lives in the web-monorepo repo and ships together.
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
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.
Prompted by a real incident: the whole /research/bionlp/RESTful/* tree returned 503 "no healthy upstream" for hours while the rest of NCBI was fine, but we reported it to users as "this article has no full text" and PmcBiocFetcher logged nothing at all, so the outage was invisible server-side.
Transport failures / 5xx / 429 now raise UpstreamUnavailableException -> terminal upstream-unavailable (not cached, not publishable), kept distinct from text-unavailable since the two call for opposite user actions. Added log4j logging (error/warn/info per outcome, including the response body snippet that identified this as NCBI's problem) and a javadoc note on BIOC_URL_BASE recording the PubTator3 endpoint as a verified fallback source. Replaced the unused HttpClient constructor seam with a narrow BiocHttpExchange interface so every branch of the failure taxonomy is unit-testable without network.
Front-end companion change (new upstream-unavailable status, messaging, recovery buttons) lives in the web-monorepo repo and ships together. VEuPathDB/web-monorepo#1843
Screenshot of new behaviour from the accompanying front end PR (old behaviour below)
Old behaviour