Computational APIs•Epistemic & System Error Taxonomy

Error Codes & Epistemic Failures

Unlike standard SaaS APIs that only report database or network errors, AION reports Epistemic Errors—explicitly halting computation whenever a query asks the system to speculate, fabricate evidence, or violate the 15 Constitutional Laws.

Canonical Error Envelope

All 4xx and 5xx responses return a structured JSON envelope with machine-readable codes and remediation advice:

{
  "error": {
    "code": "E_UNVERIFIED_POPULATION_CLAIM",
    "httpStatus": 422,
    "message": "Population generalization rejected: media discourse cannot be attributed to national population sentiment without NBS census data.",
    "constitutionalLaw": "Law 5: Population claims require population evidence.",
    "remediation": "Narrow query scope to reported media discourse or specify an explicit dataset domain."
  }
}

Epistemic & System Error Reference

Error Code	HTTP Status	Origin	Description
E_INSUFFICIENT_EVIDENCE	422 Unprocessable Entity	Law 1 & 7	Triggered when a query demands definitive claims but the substrate possesses insufficient primary evidence. AION refuses to hallucinate.
E_UNVERIFIED_POPULATION_CLAIM	422 Unprocessable Entity	Law 5	Triggered when a prompt asks for population-level assertions ('What do all Nigerians think?') without NBS demographic survey proof.
E_TEMPORAL_OUT_OF_BOUNDS	400 Bad Request	Law 2	Requested start date precedes substrate historical baseline (2015-01-01) or requests predictive future speculation.
E_EVIDENCE_NOT_FOUND	404 Not Found	Law 3	The requested evidence record or cryptographic SHA-256 snapshot does not exist in local records or Cloudflare R2 / S3 storage.
E_RATE_LIMIT_EXCEEDED	429 Too Many Requests	Infrastructure	Your API key exceeded its tier limit. Respect the Retry-After header and implement exponential backoff.
E_UNAUTHORIZED_KEY	401 Unauthorized	Security	Missing, expired, or malformed X-AION-Key header.

Retry Logic & Exponential Backoff

For 429 Too Many Requests and 503 Service Unavailable, inspect the Retry-After header (in seconds). Implement exponential jitter backoff:waitMs = min(30000, (2 ** attempt) * 1000 + random(0, 1000))

Benchmark Suite

The 20 Golden Longitudinal Questions

View Golden Benchmarks →