Error handling

All errors return a consistent JSON structure:

{
  "error": "MISSING_FILE",
  "message": "No file was uploaded. Attach a file using the 'file' form field.",
  "request_id": "d4e5f6a7-...",
  "details": { }
}

error — Machine-readable error code (use this for programmatic handling)
message — Human-readable description
request_id — Unique ID for support tracing
details — Additional context (optional, included on some errors)

Error Codes

Upload Errors

Code	HTTP	Description
`MISSING_FILE`	400	No file attached
`EMPTY_FILE`	400	File is 0 bytes
`FILE_TOO_LARGE`	413	Exceeds 100MB limit
`INVALID_FILE_TYPE`	415	Not PDF/PNG/JPG/TIFF/BMP

Validation Errors

Code	HTTP	Description
`MISSING_DOCUMENT_TYPE`	400	`document_type` not provided
`INVALID_DOCUMENT_TYPE`	400	Unrecognized document type
`DOCUMENT_TYPE_NOT_ALLOWED`	403	Org not authorized for this type
`INVALID_DOCUMENT_ID`	400	ID is not a valid positive integer
`INVALID_BASE64`	400	Base64 string is malformed
`EMPTY_BASE64`	400	Base64 decodes to empty content
`MISSING_FILENAME`	400	`filename` required with `file_base64`
`MISSING_FILE_SOURCE`	400	Neither `file_url` nor `file_base64` provided
`INVALID_FILE_URL`	400	URL is malformed or uses unsupported protocol
`FILE_URL_DOWNLOAD_FAILED`	400	Could not download from URL (403=private bucket needs presigned URL, 404=file not found, timeout)
`INVALID_WEBHOOK_URL`	400	Webhook not a valid HTTP/HTTPS URL

Batch Errors

Code	HTTP	Description
`MISSING_BATCH_DOCUMENTS`	400	`documents` array missing or empty
`BATCH_TOO_LARGE`	400	More than 100 documents
`UPGRADE_REQUIRED`	403	Batch not available on free tier

Merge Errors

Code	HTTP	Description
`MERGE_MIN_FILES`	400	Fewer than 2 files
`MERGE_MAX_FILES`	400	More than 50 files
`MERGE_UNSUPPORTED_TYPE`	400	File type not supported for merge

Resource Errors

Code	HTTP	Description
`DOCUMENT_NOT_FOUND`	404	Document doesn't exist or not in your org
`JOB_NOT_FOUND`	404	Processing job not found
`BATCH_NOT_FOUND`	404	Batch doesn't exist or not in your org

Export Errors

Code	HTTP	Description
`MISSING_DOCUMENT_IDS`	400	`document_ids` not provided
`INVALID_EXPORT_FORMAT`	400	Format not `json`, `csv`, or `excel`
`INVALID_EXPORT_TYPE`	400	No export schema available for this document type
`DOCUMENT_NOT_PROCESSED`	400	Document has not finished processing yet

Server Errors

Code	HTTP	Description
`STORAGE_ERROR`	502	File storage failed — retry
`QUEUE_ERROR`	502	Processing queue failed — retry
`INTERNAL_ERROR`	500	Unexpected server error

Handling Errors in Code

import requests
 
response = requests.post(
    "https://api.kita.ai/api/v1/documents",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    files={"file": open("statement.pdf", "rb")},
    data={"document_type": "bank_statement"}
)
 
if response.status_code == 202:
    data = response.json()
    print(f"Processing: {data['status_url']}")
elif response.status_code == 413:
    print("File too large — max 100MB")
elif response.status_code == 502:
    error = response.json()
    if error["error"] in ("STORAGE_ERROR", "QUEUE_ERROR"):
        print("Temporary failure — retry in a few seconds")
else:
    error = response.json()
    print(f"Error {error['error']}: {error['message']}")

const res = await fetch("https://api.kita.ai/api/v1/documents", {
  method: "POST",
  headers: { Authorization: "Bearer YOUR_API_KEY" },
  body: formData,
});
 
if (res.status === 202) {
  const { status_url } = await res.json();
  // Poll status_url until status is "completed" or "failed"
} else {
  const { error, message, request_id } = await res.json();
  console.error(`${error}: ${message} (ref: ${request_id})`);
}

Error handling

On this page