# ADR-019: Integration Adapter Registry

# 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.