Error Codes

All Klervex API errors use the KLV_ prefix followed by a category and number.

Error Format

{
  "error": {
    "code": "KLV_VALIDATION_001",
    "message": "Human-readable error description",
    "field": "path.to.field"
  }
}

Authentication Errors

Code	HTTP Status	Description
KLV_AUTH_001	401	Missing or invalid API key
KLV_AUTH_002	401	API key expired or revoked
KLV_AUTH_003	403	Insufficient permissions

Validation Errors

Code	HTTP Status	Description
KLV_VALIDATION_001	400	HS code not found in destination country tariff
KLV_VALIDATION_002	400	Party matches sanctions list entry
KLV_VALIDATION_003	400	Invalid port code (not in UN/LOCODE)
KLV_VALIDATION_004	400	Incoterms mismatch with transport mode
KLV_VALIDATION_005	400	Required field missing
KLV_VALIDATION_006	400	Total value does not match line items
KLV_VALIDATION_007	400	Country-specific rule violation

Extraction Errors

Code	HTTP Status	Description
KLV_EXTRACT_001	400	Unsupported file format
KLV_EXTRACT_002	422	Could not extract data from document
KLV_EXTRACT_003	413	File too large (max 10MB)

Document Errors

Code	HTTP Status	Description
KLV_DOC_001	400	Shipment not validated — validate before generating
KLV_DOC_002	400	Unsupported document type
KLV_DOC_003	500	Document generation failed

Resource Errors

Code	HTTP Status	Description
KLV_NOT_FOUND	404	Resource not found
KLV_CONFLICT	409	Resource already exists

Rate Limit Errors

Code	HTTP Status	Description
KLV_RATE_001	429	API rate limit exceeded
KLV_QUOTA_001	429	Daily extraction quota exceeded
KLV_QUOTA_002	429	Daily validation quota exceeded