Errors

Every endpoint uses the standard project envelope (internal/http/response.JSON) and the same response.Error* helpers as the rest of the API.

Error envelope

{
  "message": "<human-friendly summary>"
}

errors[] (the per-field validation array used elsewhere) is not populated by this module — query params are clamped/normalised rather than validated, so the only 400-class errors here carry plain message strings.

Content-Type: application/json always.

Status code map

There is no 401/403 — the module is fully public.

Soft-failure philosophy

Where the API can produce a useful page despite missing/dirty input, it does. Silent normalisation is preferred over a 4xx that would block the entire response:

This means a fat-fingered URL in the FE almost never produces a 400 — it produces a "best effort" response with a hint surfaced via excludedPeers, note, or implicit defaulting.

Per-endpoint quick lookup

400 messages

These surface when a value can't be normalised back to a whitelist:

Symbol path-param validation: an empty {symbol} returns 400 symbol is required. The chi route pattern rejects empty path segments before the handler runs in normal usage, but the explicit check guards against unusual middleware ordering.

404 messages

Every "symbol unknown" error uses the same message regardless of which endpoint surfaces it:

{ "message": "Company not found" }

The 404 is raised the first time the handler hits Store.GetFundamentalsSnapshotCore (or GetFundamentalsOwnershipCore for ownership) and the row is missing. Several endpoints reuse the snapshot core query as a 404 probe before doing more expensive work — this is cheap (one row from fundamentals_snapshot) and saves a multi-query trip for non-existent symbols.

Examples

$ curl -i "$BASE/api/nepse/companies/NOTASYMBOL/fundamentals/snapshot"
HTTP/1.1 404 Not Found
{"message":"Company not found"}

$ curl -i "$BASE/api/nepse/companies/NABIL/fundamentals/ratios?tab=foo"
HTTP/1.1 400 Bad Request
{"message":"invalid tab; expected valuation | profitability | solvency | growth"}

# NABIL is a Commercial Bank; NTC is Telecommunications.
$ curl "$BASE/api/nepse/companies/NABIL/fundamentals/peers?symbols=NTC"
HTTP/1.1 200 OK
{
  "data": {
    "companies": [ { "symbol": "NABIL", "isFocal": true, … } ],
    "excludedPeers": [ { "symbol": "NTC", "reason": "different_sector" } ],
    …
  }
}

$ curl "$BASE/api/nepse/companies/NABIL/fundamentals/statements?type=cashflow"
HTTP/1.1 200 OK
{
  "data": {
    "type": "cashflow",
    "available": false,
    "reason": "Cash flow statements are not currently provided by upstream (NEPSE MDP). Will be enabled once available.",
    "rows": [],
    …
  }
}

Implementation

• Envelope: internal/http/response/response.go
• Validation helpers: response.NewValidation(...), response.NewNotFound(...)
• URL param case-fold: handlerutil.URLParamUpper(r, "symbol")
• Query int clamping: fundhandlerutil.ClampedQueryInt(r, name, default, lo, hi)