Auth failures
Check the key prefix
Organization API keys must start with kh_. The auth provider throws early if the prefix does not match.
Troubleshooting
Errors, retries, and setup.
This page collects the common places where integrations fail: invalid credentials, temporary 404s during execution polling, timeout behavior, rate limits, and build-time issues.
Error mapping
The SDK converts HTTP responses into typed error classes so your app can branch by status category rather than parsing raw messages.
| Status / condition | SDK error | Meaning |
|---|---|---|
| 400 | ValidationError | The request payload failed validation |
| 401 / 403 | AuthError | API key or credentials are missing or invalid |
| 402 | PaymentRequiredError | The workflow or endpoint requires payment |
| 404 | NotFoundError | The resource does not exist or has not been indexed yet |
| 422 | SpendingCapError | Execution exceeded the spending cap |
| 429 | RateLimitError | Retry-after and backoff may apply |
| 5xx | ServerError | The KeeperHub backend experienced a server-side failure |
| Timeout | KeeperKitError | The request timed out before a response arrived |
| Network failure | KeeperKitError | The request could not reach the server |
Execution polling
Retry short-lived 404s
If an execution was accepted but the status record is not indexed yet, retry for a brief period before surfacing a failure.
Build issues
Rebuild the SDK dist output
If a consumer project sees stale types or runtime code, rebuild SDK/ so dist/ stays in sync with the source tree.
Rate limits
Respect retry-after headers
The HTTP client uses exponential backoff and honors Retry-After when the server sends it.
Validation commands
These are the commands the SDK README already recommends for day-to-day development and verification.
cd SDK
pnpm install
pnpm test
pnpm type-check
pnpm buildDo not treat an immediate 404 after a successful execute call as a permanent failure. KeeperHub may accept the run before the execution record is visible to the status endpoint.