Validation and Errors

Every agency SDK validates external responses at runtime with Zod. TypeScript tells you what your code expects; Zod checks what the agency actually returned.

This matters for official statistics because upstream APIs change in small, inconvenient ways: nullable fields appear, documented fields disappear, error payloads reuse status codes, and CSV exports add columns without notice. The SDKs make those changes visible instead of silently passing corrupted assumptions into your app.

Validation boundary

Validation happens after the HTTP response is received and before data is returned to your code.

const client = new StatCanClient();
const result = await client.getDataFromVectorsAndLatestNPeriods([
  { vectorId: 41690973, latestN: 12 },
]);
 
// If this line runs, the response matched the SDK schema.
console.log(result[0].object?.vectorDataPoint);

If the agency returns a structurally different payload, the client throws before your application treats the response as trusted data.

Error classes

Every package exports one or more typed error classes. At minimum, non-2xx responses include the HTTP status, request URL, and raw body.

import { WorldBankApiError } from '@varve/worldbank-api';
 
try {
  await client.getIndicator('missing');
} catch (err) {
  if (err instanceof WorldBankApiError) {
    console.error(err.status);
    console.error(err.url);
    console.error(err.body);
  }
}

Some packages expose more specific errors when the upstream API has well-known failure modes. For example, @varve/statcan-wds distinguishes invalid coordinates, agency internal errors, suppressed data, and malformed agency responses.

Practical rule

Treat SDK responses as verified at the shape level, not as a guarantee that every number is analytically appropriate for your use case. You still choose the indicator, geography, period, frequency, and transformation. The SDK verifies that the official source returned the shape it claims to return.

Working with schema failures

A schema failure usually means one of three things:

• the agency changed its response shape
• the request reached an undocumented edge case
• the SDK schema needs to become more tolerant without hiding ambiguity

When reporting an issue, include the package, method, request parameters, status code if available, and a redacted sample of the raw response.