Errors
Error codes from the SDK and the Server API, and what to do about each.
In the SDK
These reach onError as code. The borrower sees a plain-language message for
each and can usually fix it on the spot.
| Code | Cause | What happens |
|---|---|---|
encrypted_pdf | The PDF needs a document password. | The flow asks for it. |
invalid_pdf_password | Wrong document password. | The borrower can retry. |
unsupported_format | Not a PDF or supported image, or a video. | The borrower picks another file. |
invalid_image, corrupt_pdf, empty_document | The file cannot be opened. | The borrower picks another file. |
document_too_large, too_many_pages, oversized_image | Over a limit. | The borrower picks a smaller copy. |
multiple_image_frames | An animated or multi-frame image. | Export pages as a PDF or separate photos. |
document_limit_reached | 12 files already uploaded. | Remove one first. |
connection_error, rate_limited | Network trouble or throttling. | The flow offers Retry. |
client_token_expired, invalid_client_token, missing_client_token | The 30-minute token ran out, was replaced, or was not sent. | Get a new client token and reopen. |
session_locked | The files were already shared. | Nothing to do; the session shows its receipt. |
From the Server API
| Status | Code | Fix |
|---|---|---|
| 401 | missing_api_key | Send your key in the X-API-Key header. |
| 401 | invalid_api_key | The key matches no organization. Check for a truncated or rotated key. |
| 401 | wrong_environment | Use a risk_test_ key on test and a risk_live_ key on production. |
| 403 | origin_not_allowed | origin must exactly match an origin registered with Kita: scheme, host and port, no path. |
| 403 | profile_not_enabled | The model profile is not enabled for your organization. |
| 404 | session_not_found | Wrong ID, another organization's session, or expired. |
| 409 | idempotency_conflict | Same Idempotency-Key, different body. Use one key per applicant. |
| 409 | results_not_ready | Wait for the webhook or for a terminal status. |
| 413 | request_too_large | The request exceeded the size limit. |
| 422 | invalid_request, market_profile_not_validated | A field failed validation, or country does not match your profile. |
| 429 | rate_limited | Wait for Retry-After seconds. |
| 503 | archive_unavailable | Deletion could not reach the archive. Nothing was removed; retry. |
A file that could not be read
A session can finish as partial or failed. Each document then carries a
reason: model_rejected or blank_document (not a readable financial
document), extraction_error (every provider failed), or processing_timeout.
The borrower is not shown these after sharing; decide in your own flow whether
to ask for a clearer copy.