KERNIT Documentation
Errors and Troubleshooting
Treat KERNIT API errors by class: fix request shape for 400, auth for 401, billing for 402, back off for 429, and treat 5xx responses as KERNIT-side service availability or processing failures.
ALL
api.kernit.org document routes
Error Handling Model#
Errors are intentionally separated into request-shape, authorization, billing, rate-limit, route, and KERNIT-side availability classes so clients can distinguish client-fixable errors from KERNIT-side availability incidents.
| Status | Common cause | Handling |
|---|---|---|
| 400 | Missing file, invalid JSON settings, invalid DOCX package. | Fix the request shape before sending it again. |
| 401 | Missing Bearer token, invalid key, invalid scan token, file/settings mismatch. | Correct auth or preserve scan/apply state. |
| 402 | No available API credits or plan allowance. | Top up credits or change billing plan. |
| 404 | Wrong public route, often using /api on api.kernit.org. | Use bare routes such as /hyperlink-scan. |
| 429 | Per-key or organization rate limit. | Respect Retry-After. |
| 503 | KERNIT server-side processing is temporarily unavailable or the resolver stream failed. | Do not treat this as a client integration bug. Keep the error body and request time for KERNIT support if it repeats. |
Error Handling Rules#
- Request-shape, auth, billing, and route errors should be fixed by the client.
- 5xx errors are KERNIT-side processing or availability failures.
- For repeated 5xx responses, keep diagnostic context for KERNIT support instead of treating the response as an integration bug.
Error Response Contract#
| Field | Meaning |
|---|---|
error | Human-readable error summary. Always present. |
reason | Machine-readable detail for known validation classes, including scan-token mismatch causes. |
hint | Optional next-step guidance when the caller can fix the request. |
requestId | Support correlation id when the platform can expose one. |
retry_after | Delay in seconds for 429 rate-limit responses. |
Common Error Bodies#
Invalid request
{
"error": "DOCX rejected",
"reason": "missing_file"
}Missing auth
{
"error": "Missing authorization header"
}No credits
{
"error": "No API credits available",
"dashboard": "https://api.kernit.org/dashboard"
}Wrong route
{
"error": "Not found",
"hint": "Use /hyperlink-scan, not /api/hyperlink-scan, on api.kernit.org"
}Scan mismatch
{
"error": "Scan token validation failed",
"hint": "Use the same file, settings, scanFingerprint, and decisions from scan"
}KERNIT availability
{
"error": "Service unavailable",
"requestId": "req_01HY4Q9M2V6R8K9Z4G7T2S1P0A"
}Expected Handling#
| Error class | Show users | Log for support |
|---|---|---|
| 400 request shape | Ask for the missing file, valid settings JSON, or a valid DOCX. | Endpoint, status, validation reason. |
| 401 auth or scan state | Ask the user to check the API key or restore the original scan/apply state. | Endpoint, status, key id if available, scanFingerprint. |
| 402 billing | Send the user to credits, plan, or team billing. | Endpoint, status, organization id or account id. |
| 429 rate limit | Show the Retry-After time and keep the operation pending. | Endpoint, status, Retry-After header. |
| 5xx KERNIT availability | Say the document could not be processed right now. | Endpoint, status, request time, request id, scanFingerprint, and settings hash. |
Was this page useful?Send a lightweight docs feedback event.