Documentatie / Naslag

Foutcodes

De body van een fout ziet er altijd hetzelfde uit. Ga uit van code, niet van de tekst: die is geschreven voor mensen en kan veranderen.

JSON

{ "error": { "code": "duplicate_order", "message": "Er is al een factuur aangemaakt voor deze order_id" } }

Wanneer opnieuw proberen veilig isBij 429, 500, 503, idempotency_in_progress en netwerkfouten — met dezelfde Idempotency-Key: er ontstaat geen duplicaat.

Request en toegang

HTTP	code	Oorzaak en wat te doen
400	`bad_json`, `bad_body`	De body is geen JSON, bevat overbodige velden of een bedrag als getal in plaats van string — corrigeer het request
400	`bad_idempotency_key`	Sleutel ontbreekt of heeft een ongeldig formaat: 8–128 afdrukbare ASCII-tekens, begint niet met `d:`
400	`bad_query`	Ongeldige parameters voor de lijst
401	`unauthorized`	Handtekening, tijd, nonce of sleutel — zie CP-HMAC
403	`merchant_suspended`	De merchant is opgeschort — neem contact op met support
403	`merchant_not_approved`	De aansluiting is niet afgerond of de aanvraag wordt beoordeeld — rond de wizard in het dashboard af
403	`billing_suspended`	Een factuur voor de commissie is niet betaald — betaal die in het dashboard onder ‘Facturering’; de opschorting wordt direct opgeheven
404	`not_found`	De factuur bestaat niet of hoort bij een andere merchant
413	`body_too_large`	De body is groter dan de limiet — maak `metadata` kleiner
429	`rate_limited`	Te veel requests — probeer opnieuw met exponentiële backoff
500	`internal`	Interne fout — probeer opnieuw met dezelfde `Idempotency-Key`

Facturen en idempotentie

HTTP	code	Oorzaak en wat te doen
409	`duplicate_order`	`order_id` is al gebruikt — kies een nieuwe, bijvoorbeeld `ORDER-1001-2`
409	`idempotency_conflict`	Dezelfde sleutel met een andere body
409	`idempotency_in_progress`	Het eerste request wordt nog verwerkt — probeer het over 1–2 s opnieuw
409	`invoice_not_payable`	De factuur is verlopen of gesloten — maak een nieuwe aan
422	`invalid_order_id`, `invalid_price_amount`, `invalid_price_currency`, `invalid_return_url`, `invalid_expires_in_seconds`, `invalid_metadata`	Het veld is niet door de validatie gekomen — de tekst noemt de regel
422	`invalid_allowed_assets`	Geen enkele asset uit de lijst is beschikbaar — de tekst geeft per asset de reden
422	`no_assets`	Er is geen enkele asset beschikbaar — controleer wallets en assets in het dashboard
422	`amount_too_small`	Het bedrag ligt onder het minimum van alle beschikbare assets

Valutakeuze op de betaalpagina

Deze fouten worden door de betaalpagina afgehandeld — uw server krijgt ze alleen te zien als u select zelf aanroept.

HTTP	code	Oorzaak
409	`asset_locked`	Wisselen van valuta na een betaling
409	`wallet_not_configured`	Geen actieve ontvangstwallet voor dit netwerk
409	`wallet_changed`, `address_conflict`	Maak de keuze opnieuw
422	`asset_not_allowed`	De asset hoort niet bij de factuur of is niet meer toegestaan
503	`rate_unavailable`	Geen bevestigde koers — bied een stablecoin aan
503	`network_unavailable`	Ontvangen op dit netwerk is tijdelijk niet mogelijk — kies een ander netwerk

Terugbetalingen

HTTP	code	Oorzaak
403	`merchant_inactive`	De winkel is opgeschort of de sleutel is ingetrokken
409	`invoice_not_paid`	Voor de factuur is geen asset gekozen — er valt niets terug te betalen
409	`nothing_to_refund`	Alles is al terugbetaald of aangevraagd
409	`too_many_refunds`	20 openstaande aanvragen voor de factuur
409	`refund_executor`	De terugbetaling wordt door het platform uitgevoerd, niet door u
409	`invoice_status_changed`	De status van de factuur is na de aanvraag gewijzigd — probeer opnieuw met `"ack_status_change": true`
422	`amount_exceeds_refundable`	Het bedrag is hoger dan beschikbaar — verlaag het of gebruik `"full"`
422	`invalid_amount`, `invalid_address`, `invalid_tx_hash`	Het veld is niet door de validatie gekomen