Foutcodes
Elke negatieve code en HTTP-status in de CPI-foutencatalogus, wat ze betekenen en wat je kunt doen.
Xuda houdt één catalogus bij van elke fout waarmee een aanroep kan terugkomen. Deze pagina is die catalogus, geordend naar waar de fout verschijnt. Zie Errors voor de API-specifieke uitleg van dezelfde codes.
HTTP-statusfouten
Dit zijn de statussen die je ziet op de transportlaag, of je nu direct een pagina opent of een
cpi-aanroep doet.
Codes voor het clientcontract
De eigen client van het dashboard herkent deze codes en start er een specifieke UI-stroom mee in
plaats van een algemene foutmelding. Facturatie is van een prepaid saldo overgegaan op postpaid
facturen, dus de enige drempels die nog overblijven bij een betaalde actie zijn een ontbrekende
kaart en een achterstallige factuur. -92 (negatief saldo) en -93 (opwaardering nodig) komen niet
meer uit de accountcontrole die ze vroeger gaf. In de client bestaat nog een -93-handler voor
compatibiliteit, maar er is niets meer dat hem activeert.
De responsenvelop
Elke methode, bij succes of falen, antwoordt met { code, data }. code >= 1 is succes; code < 0
is een fout. Sommige fouten op de HTTP-laag voegen naast de numerieke code een tekstsleutel
error toe ("rate_limited", "invalid_fields", "appeal_failed"), soms met een array
fields: [].
CPI vertaalt een negatieve code met één regel naar een HTTP-status: een code van -400 tot en met
-499 wordt precies die status (-400 zelf geeft HTTP 400, -404 geeft HTTP 404, -409 geeft
HTTP 409, -428 geeft HTTP 428). Elke andere negatieve code, -1, -500, -762, -999, alles
buiten die ene band, geeft ook gewoon HTTP 400. Een paar aparte, smallere endpoints (een paar routes
voor storefront-checkout en openbare formulieren, niet de algemene /cpi/<method>-dispatch) vertalen
alleen -404/-403/-400 en geven voor al het andere standaard 422. Die vertaling is lokaal voor
die routes en beschrijft niet de algemene regel hierboven: een -400 van de algemene dispatch is
dus HTTP 400, niet 422.
Hetzelfde getal wordt bij verschillende methoden hergebruikt met een andere betekenis, vooral -1 en
-400. Lees altijd het bericht in data en kijk naar de methode die je hebt aangeroepen: de
betekenissen hieronder zijn het gewone geval, geen garantie.
Negatieve CPI-codes
De codes waarop het de moeite waard is te vertakken, verzameld uit een scan van elke cpi/*_module.
Naast deze tabel gebruiken afzonderlijke modules kleine negatieve codes (ongeveer -2 tot en met
-25, -44/-45/-46, -64 tot en met -78, -99/-101/-106) voor modulespecifieke
tussentoestanden. Ze komen bijna altijd samen met een beschrijvend bericht in data, vaak
err.message. Lees dan de tekst in data en de methode waar hij vandaan komt, en leun niet alleen
op het getal.
Interne / niet-gedeclareerde fouten
Een handvol fouten bereikt de { code, data }-envelop nooit: een niet-afgevangen exception, een
onafgehandelde promise rejection, een throw new Error(...) die als kale 401 of 500 verschijnt
(bijvoorbeeld 'app is off', 'Account suspended', 'Account terminated'), of een fout in de
message broker. Deze herken je aan hun vorm of bron in plaats van een vaste code, en ze zijn altijd
de moeite van escaleren waard in plaats van blind opnieuw proberen.