Kepler Insights API

Every error response has the same shape:

{
  "error":   "stable_string_code",
  "message": "Human-readable hint",
  "reason":  "Optional extra context (rate-limit endpoints)"
}

Branch on error, not on message. The error string is stable across versions; message may be tightened or expanded.

4xx — caller errors

Status	`error`	Cause	Recover
400	`body.domain required`	POST body had no `domain` field.	Add it.
400	`sandbox: only [...] supported`	Live domain with a test key.	Use a `ki_test_` key for sandbox, `ki_live_` key for real.
400	`test domains require a ki_test_ key`	Test domain with a live key.	Same — match domain to key prefix.
400	`invalid_cursor`	History pagination cursor malformed.	Drop the cursor (start over) or use the `next_cursor` we returned.
400	`window must be one of ['7d','30d','90d']`	Bad `?window=` value on `/v1/movers`.	Use a supported value.
401	`unauthorized`	Missing or invalid `X-API-Key`.	Check the header is set and the key is active. Allow up to 5 min for revocations to propagate.
403	`free_tier_sandbox_only`	Live key on Free tier attempted a real-domain score. The Free trial is sandbox-only.	Use a `ki_test_` key against the 4 canned test domains, or upgrade to Starter.
403	`forbidden`	Job belongs to a different account.	Job IDs are bound to the user that started them — any of that user’s keys can poll, but keys from another account cannot.
404	`no score available for this domain`	`GET /v1/score/{domain}` against a never-scored domain.	Trigger one with `POST /v1/score`.
404	`no_history`	Same shape, history endpoint.	Trigger an initial score.
404	`job not found`	Unknown or expired (>30d) job ID.	Re-run `POST /v1/score` to start a fresh cold pipeline.
429	`cold_budget_exhausted` (`reason: monthly_cap`)	Account exhausted its tier’s monthly cold-call budget. v1.0 is flat-only — no overage.	Upgrade to the next tier, or wait for the next monthly reset (`Retry-After` header gives seconds remaining). v1.5 will add opt-in metered overage.
429	`rate limited` (`reason: per_key_cold_1h`)	This key hit 200 cold calls in 1 hour.	Wait — `Retry-After` header gives seconds until reset.
429	`rate limited` (`reason: account_cold_24h`)	Account hit 2× tier monthly cold cap inside 24h.	Wait, or email support if legitimate spike.

5xx — server / pipeline errors

Status	`error`	Cause	Recover
500	`internal error`	Unhandled exception.	Retry once. If persistent, email support with `requestId` from headers.
500	`sandbox_invariant_violated`	A sandbox key reached a live-path codepath. Should never fire — alerts us when it does.	Retry; email support so we can investigate the regression.
500	`scoring engine unavailable`	The scoring pipeline failed to start.	Retry once; email support if persistent.

How cold scoring fails after kickoff

A successful POST /v1/score cold path returns 202 with a job_id immediately, then queues the run. If the engine later fails to produce a score (insufficient data, fetcher credit exhaustion, etc.), the corresponding GET /v1/jobs/{job_id} poll returns:

{ "status": "failed", "failure_reason": "scoring_completed_no_record" }

Possible failure_reason values: sfn_failed, sfn_timed_out, sfn_aborted, scoring_completed_no_record. Retry with a different domain, or wait a few hours and re-run — fetcher credit exhaustion clears on the daily rollover. See GET /v1/jobs/{job_id} for the full response shape.

What we never do

Surface fetcher errors directly. A data fetcher timeout becomes a data_warnings entry in GET /v1/company/{domain}/confidence, not a 5xx. The score is still produced.
Return partial data on 200. A 200 response always has the full schema. Missing data appears as neutral defaults (signal score ≈ 50) flagged in confidence.
Auto-retry your call on a 4xx. If you sent bad input, retrying doesn’t help.