Error Handling

API errors

Code	Meaning	Fix
`400`	Bad request / validation	Check field formats (org numbers, country codes)
`401`	Invalid token	Refresh OAuth token
`403`	Missing scope	Add scope to OAuth client
`404`	Not found	Check IDs, or no access
`409`	Conflict	Duplicate (e.g. issuer transaction state ID)
`422`	Business rule	e.g. delete signed signatory

Issue	Cause	Fix
HTML login page instead of JSON error	Missing `Accept: application/json`	Send `Accept: application/json` on every API call
Webhook `active=false`	Challenge failed	Implement HMAC challenge handler
No transactions	TPA not activated	Wait for issuer card confirmation
No transactions	PDPC not signed	Cardholder must sign consent
Duplicate txs	Same transaction received twice	Upsert by transaction `id`
Wrong VAT on tx	Network VAT, not merchant	Subscribe to `transaction.true.vat`