Error Codes
When something goes wrong, ClapPay tells you what happened with an error code. This guide explains what each error means and how to fix it.
How Errors Work
When an API request fails, ClapPay returns an error object with details about what went wrong:
{
"error": {
"type": "card_error",
"code": "card_declined",
"message": "Your card was declined.",
"decline_code": "insufficient_funds",
"param": "payment_method"
}
}The type tells you the category of error. The code anddecline_code tell you exactly what went wrong.
Error Types
card_error
Something wrong with the card. The customer needs to fix this.
Examples: Card declined, expired card, wrong CVC
authentication_error
Problem with your API key. Check your credentials.
Examples: Invalid API key, wrong key for mode (test vs live)
rate_limit_error
Too many requests. Slow down and try again.
Wait a few seconds and retry the request
invalid_request_error
Something wrong with the request you sent. Fix your code.
Examples: Missing required field, invalid parameter value
api_error
Something went wrong on our end. Rare, but it happens.
Wait and retry. Check our status page if it continues.
Common Decline Codes
When a card is declined, the decline_codetells you why. Here's what to do for each:
| Code | What Happened | What to Tell Customer |
|---|---|---|
| insufficient_funds | Not enough money | "Try a different card or add funds" |
| card_declined | Bank said no (generic) | "Contact your bank or try another card" |
| expired_card | Card is expired | "Your card has expired. Please update it" |
| incorrect_cvc | Wrong security code | "Check the security code on your card" |
| incorrect_number | Card number is wrong | "Check your card number" |
| lost_card | Card reported lost | "This card cannot be used. Try another" |
| stolen_card | Card reported stolen | "This card cannot be used. Try another" |
| do_not_honor | Bank won't say why | "Contact your bank or try another card" |
| fraudulent | Suspected fraud | "Payment declined. Contact your bank" |
3D Secure Errors
These errors happen when the bank requires extra verification:
| Code | What It Means |
|---|---|
| authentication_required | Customer needs to complete 3D Secure |
| authentication_failed | Customer failed 3D Secure (wrong code) |
| card_not_supported | Card doesn't support 3D Secure when required |
Handling Errors in Code
Always wrap API calls in try/catch to handle errors:
const clappay = require('@clappay/sdk')('sk_live_...');
try {
const payment = await clappay.paymentIntents.create({
amount: 2000,
currency: 'usd',
payment_method: 'pm_card_declined',
confirm: true,
});
} catch (error) {
switch (error.type) {
case 'card_error':
// Tell customer what's wrong with their card
console.log('Card error:', error.message);
console.log('Decline code:', error.decline_code);
break;
case 'invalid_request_error':
// Bug in your code
console.log('Invalid request:', error.message);
break;
case 'rate_limit_error':
// Wait and retry
await sleep(1000);
// retry...
break;
case 'authentication_error':
// Check your API keys
console.log('Auth error:', error.message);
break;
default:
// Unexpected error
console.log('Unknown error:', error.message);
}
}Show User-Friendly Messages
Don't show raw error codes to customers. Translate them into helpful messages:
function getCustomerMessage(error) {
const messages = {
'insufficient_funds': 'Your card doesn\'t have enough funds. Try a different card.',
'card_declined': 'Your card was declined. Please contact your bank or try another card.',
'expired_card': 'Your card has expired. Please use a different card.',
'incorrect_cvc': 'The security code is incorrect. Check the back of your card.',
'incorrect_number': 'The card number is incorrect. Please check and try again.',
'processing_error': 'Something went wrong. Please try again.',
};
return messages[error.decline_code] ||
messages[error.code] ||
'Payment failed. Please try again or use a different card.';
}When to Retry
Some errors are temporary and worth retrying. Others are permanent:
✓ Worth retrying
- •
rate_limit_error- Wait and try again - •
api_error- Our servers had a hiccup - • Network timeouts - Connection issue
✗ Don't retry
- •
card_declined- Customer needs a different card - •
expired_card- Card won't work - •
authentication_error- Fix your API key - •
invalid_request_error- Fix your code
Common Mistakes
Using test keys in production
You'll get an error if you try to charge a real card with a test key. Make sure to switch to live keys before going live.
Wrong currency format
Amounts should be in the smallest unit (cents for USD). To charge $10, use amount: 1000, notamount: 10.
Missing required parameters
Check the API docs for required fields. For example, PaymentIntents need both amount andcurrency.