{ "available": false, "reason": "..." }, and schema 2 uses { "unavailable": "..." }. Do not turn either form into null, 0, or a hidden chart gap.
This page documents the main deliberate absences. They are not backlog promises. When there is a truthful alternative, use the served fields or the recovery object. When the API cannot prove the metric, the correct answer is the refusal.
Negative P/E
Refused:price_to_earnings refuses with ratio_undefined_nonpositive_denominator when EPS or net income is not positive.
The multiple is non-monotonic across zero. A 0.01/share shows P/E ≈ -3,000, while a 20/share shows P/E ≈ -1. Sorting, screening, or comparing those negative multiples silently inverts the loss severity exactly where mistakes are most expensive. The industry is split: some vendors serve the negative value; Compustat-class systems and consumer sites typically blank it.
A vendor serving a negative P/E is following an honest convention on real inputs. That is not fabrication, and we do not claim it is. Fabrication is asserting a filing fact the filing does not contain, such as 0.0 for a never-reported line or revenue for a statement shape with no revenue line. StockContext refuses the negative multiple for machine-safety, not because the vendor convention is fake. The response says which is which.
Use instead: earnings_yield_pct serves signed for loss years. It is well-defined, sorts correctly through zero, and is basis-stamped net_income_over_market_cap. The served negative eps_diluted sits on the same response as proof that the P/E refusal is arithmetic, not missing data. The refusal envelope points there with recovery.action: "use_alternative_field" and field: "earnings_yield_pct".
PEG ratio
Refused:peg / PEG ratio is not a served field.
Forward PEG needs analyst consensus earnings estimates, and fundamentals here are SEC-only. Trailing PEG can look mechanical, but it silently changes meaning or breaks when earnings or EPS growth crosses zero. Serving one canonical PEG would make the API choose a caveat for the caller.
Use instead: stock_overview serves valuation.price_to_earnings plus per-field growth where available, including growth.eps_diluted.yoy_pct in schema 2 summaries. Multi-year cagr_2y_pct also serves per-field when the API can compute it; read the field’s own growth object instead of assuming every growth field has the same keys. An agent that explicitly accepts trailing-PEG caveats can compose its own value after checking that the growth denominator and latest EPS are positive.
EBITDA without filed D&A
Refused:ebitda and dependent multiples such as ev_to_ebitda refuse when the filing does not provide a depreciation-and-amortization operand on the statement face.
EBITDA is only an exact derivation when every operand is a filed value. If D&A is not on the statement face, synthesizing it from notes, roll-forwards, or vendor conventions would fabricate an operand and make the derived multiple look more certain than it is.
Use instead: when D&A is filed, ebitda serves as derived and full provenance shows operating_income + depreciation_amortization; ev_to_ebitda then serves from enterprise_value / ebitda. When it refuses, use the filed operating and cash-flow fields that did serve, such as operating_income or operating_cash_flow.
Financial-shape margins and inventory
Refused: generic COGS, gross-margin, operating-margin, and inventory-derived metrics arenot_applicable_for_shape when the filer shape does not have those lines.
Banks, brokers, BDCs, and investment companies do not use an industrial “sales minus COGS equals gross profit” statement shape. Mapping bank interest expense or BDC investment income into COGS/inventory fields would produce familiar-looking numbers, but they would not be filing-proven economic lines.
Use instead: follow recovery.field and the fields catalog. Banks and brokers expose shape-native lines such as net_interest_income; bank overview exposes efficiency_ratio_pct; BDCs expose total_investment_income, and BDC overview can serve price_to_nav when both operands are available. Other specialty shapes serve their own native analysis fields instead of generic COGS/inventory fields. Never infer any of these from COGS.
REIT FFO
Refused:ffo / affo refuse when the NAREIT adjustment lines are not tagged in XBRL.
Net income plus D&A is not FFO. REIT FFO can require gains, impairments, unconsolidated JV adjustments, noncontrolling-interest adjustments, and other bridge lines that are often not tagged on the XBRL statement face. Serving a shortcut would be worse than refusing because it would look like a filed NAREIT bridge.
Use instead: REIT overview keeps the earnings-based payout_ratio labeled with its basis and additionally serves dividends_to_ocf when dividends and operating cash flow are provable. If you need management’s FFO bridge, use the full filing; do not reconstruct it from net income and D&A.
Back-derived share counts
Refused: weighted-average share counts are never back-derived from net income divided by EPS. That arithmetic can disagree with the filed share count because EPS is rounded, share classes differ, and basic/diluted definitions are not interchangeable. A derived share count that disagrees with the filed one poisons every per-share ratio built on top of it. Use instead: useweighted_avg_shares_basic and weighted_avg_shares_diluted only when they are filed and served. For point-in-time valuation, use shares_outstanding when served. If the share operand refuses, downstream per-share metrics refuse too.
Missing is not zero
Refused: an absent filing line is never emitted as0.0.
Some data feeds collapse absence into zero, which makes “not tagged” indistinguishable from “the company reported exactly zero.” That is a silent wrong-number path, especially for dividends, buybacks, inventory, and shape-specific lines.
Use instead: keep the refusal object and branch on it. A genuinely tagged zero serves as a real zero; an unprovable value serves as a closed-vocabulary refusal reason.
Recovery and the zero-wrong gate
Refused: a value that is unverified, contradicted by the SEC oracle, or outside the extraction scope refuses instead of serving. The product gate is mechanical:known_wrong_served == 0. Coverage can be incomplete; a served wrong value cannot be accepted. That is why refusal reasons are closed-vocabulary tokens and why recovery instructions are part of the value envelope.
Use instead: read recovery before deciding what to do next. It may tell an agent to retry, use another tool, use the full document, use an alternative field, or take no action. Resolve the machine catalog with stock_reference: