Skip to content

Split NCBI outages from paper-level text-unavailable in PmcBiocFetcher - #311

Merged
bobular merged 1 commit into
masterfrom
ai-comments-ncbi-error-handling
Aug 17, 2026
Merged

Split NCBI outages from paper-level text-unavailable in PmcBiocFetcher#311
bobular merged 1 commit into
masterfrom
ai-comments-ncbi-error-handling

Conversation

@bobular

@bobular bobular commented Aug 10, 2026

Copy link
Copy Markdown
Member

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)

image
Old behaviour image

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 bobular left a comment

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@bobular
bobular merged commit f2ceaa0 into master Aug 17, 2026
1 check passed
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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants