ADR-019: Integration Adapter Registry

Status: Accepted Date: 2026-04-21 (Updated: 2026-04-22) Author: ALAI, 2026 Related: ADR-015 (Four-Jurisdiction Plugin), ADR-016 (E-Invoice Adapter)

Context

Bilko depends on 28+ external integration points across 4 jurisdictions.

[... rest of existing markdown content truncated for brevity ...]

§2.3 Error Code Taxonomy (Updated 2026-04-22)

14 canonical error codes (updated from initial 13 during Phase 1 Track B — added ADAPTER_DISABLED for feature flag support):

Connectivity (retryable=true)

NETWORK_TIMEOUT — Socket timeout, connection timeout
NETWORK_UNREACHABLE — Network unavailable, DNS failure

Authentication / Authorization (retryable=false)

AUTH_TOKEN_EXPIRED — OAuth2 token expired (caller should refresh token + retry once)
AUTH_INVALID_CREDENTIALS — Invalid API key, cert rejected
AUTH_INSUFFICIENT_PERMISSIONS — Valid credentials but insufficient permissions

Validation (retryable=false)

VALIDATION_SCHEMA_ERROR — UBL schema violation, XML parse error
VALIDATION_BUSINESS_RULE — PIB must be 9 digits (RS), OIB must be 11 digits (HR), mandatory field missing
VALIDATION_DUPLICATE_DOCUMENT — Invoice already exists in fiscal platform

Platform-side (retryable=true)

PLATFORM_MAINTENANCE — Scheduled maintenance, announced downtime
PLATFORM_RATE_LIMITED — HTTP 429, quota exceeded
PLATFORM_INTERNAL_ERROR — HTTP 5xx, platform bug

Adapter State (retryable=false)

NOT_IMPLEMENTED — Stub adapter (lifecycle state: STUB)
ADAPTER_DISABLED — Feature-flagged off per AdapterConfig.enabled (ADR-019 §3)

Generic

UNKNOWN — Unexpected error, unmapped status code (retryable=false)

Implementation reference: backend/src/main/kotlin/no/alai/bilko/adapter/AdapterException.kt

Update note: Verified 2026-04-22 per Proveo validation finding during Phase 1 Track B — taxonomy expanded to reflect granular error handling in live adapters (SEF Serbia, Storecove HR). Source ADR markdown file updated in sync.