Stripe Codes

Error Types and Categories

Stripe organizes errors into several high-level types that help categorize the nature of the problem. The most common error type is card_error, which covers issues specific to payment cards such as declines, expired cards, and insufficient funds. Another frequent type is invalid_request_error, which occurs when the API request is malformed or contains invalid parameters. Authentication errors fall under the authentication_error type, while rate limiting issues are categorized as rate_limit_error.

Common Error Types

The card_error type is particularly important because it represents the majority of payment failures encountered in real-world scenarios. These errors often require different handling strategies depending on the specific error code. For instance, some card errors indicate temporary conditions that can be resolved by retrying the payment, while others represent permanent issues that require the customer to update their payment method.

HTTP Status Codes

Stripe uses conventional HTTP response codes to indicate the success or failure of API requests. Codes in the 2xx range indicate success, with 200 being the standard response for successful operations. When an error occurs, Stripe returns status codes in the 4xx range, indicating client errors, or 5xx range, indicating server errors.

The specific 4xx status codes help identify the general category of the error:

• 2xx: Success (200 for standard operations)
• 400: Bad Request (invalid request errors)
• 401: Unauthorized (authentication errors)
• 402: Payment Required (card errors and payment failures)
• 429: Too Many Requests (rate limit errors)

Each error response includes a JSON body with detailed information about the error. The response contains fields such as error.type, error.code, error.message, and error.param (when applicable). The error.param field specifically indicates which parameter in the request caused the error, which is invaluable for debugging invalid request errors.

The card_velocity_exceeded Error Code

What Does It Mean?

The card_velocity_exceeded error code is returned when a payment attempt is declined because the customer has exceeded the balance, credit limit, or transaction amount limit available on their card. This can happen with credit cards, virtual company cards, or due to transaction limits imposed by the card issuer. This error originates from the card issuing bank and is further categorized by card networks.

Card velocity limits are security measures implemented by card issuers to prevent fraud and protect cardholders from unauthorized usage. These limits cap the number of transactions or the total transaction amount within a specific time period, such as per day or per week. When a card exceeds these limits, subsequent transactions are automatically declined until the time period resets or the cardholder contacts their bank to authorize additional transactions.

Common Causes

Several factors can trigger the card_velocity_exceeded error:

• Transaction count limits: Maximum number of transactions within a time period
• Spending amount limits: Monetary caps on daily or weekly spending
• Unusual spending patterns: Sudden spikes triggering fraud detection
• Quick succession transactions: Multiple purchases in short timeframe
• New card limits: Newly issued cards often start with lower limits
• High-risk merchant categories: Stricter limits for certain industries

Timing issues can also play a role, particularly when budget transfers or credit limit increases have been requested but not yet processed by the card issuer.

Hard vs Soft Declines

card_velocity_exceeded is a hard decline -- it cannot be resolved by retrying the transaction. When a card's velocity has been exceeded for a defined period, the customer has no choice but to use a different payment method to complete the transaction. This distinction is crucial for implementing appropriate error handling.

For subscription businesses, hard declines present a significant challenge because automatic retry attempts will not resolve the issue. Stripe does not retry hard declines automatically through their standard smart retry system, which is appropriate because retrying would simply result in repeated failures. Instead, merchants should implement their own logic to identify hard declines and trigger appropriate recovery workflows.

Handling card_velocity_exceeded in Your Integration

Best Practices

When the card_velocity_exceeded error occurs, the most effective resolution is to request that the customer update their payment method. This requires implementing a seamless customer experience that makes it easy for users to enter new card information without navigating away from your application.

1. Request payment method update: Provide a seamless way for customers to enter new card information
2. Clear user messaging: Translate technical codes into user-friendly language
3. Implement dunning workflows: Automate customer notifications for hard declines
4. Monitor and log errors: Track decline patterns and recovery rates

Recommended Customer Messaging

Instead of displaying technical error codes, communicate clearly:

"Your card has reached its transaction limit. Please try a different payment method or contact your bank to resolve this issue."

Code Example

// Handle card errors with specific codes
const handleStripeError = (error: Stripe.StripeError) => {
 switch (error.code) {
 case 'card_velocity_exceeded':
 // Hard decline - requires customer action
 showCustomerNotification(
 'Payment method needs update',
 'Your card has reached its limit. Please update your payment method.'
 );
 redirectToBillingPortal(customerId);
 break;
 
 case 'card_declined':
 // Could be temporary - offer retry
 showRetryOption('Card was declined. Try again?');
 break;
 
 default:
 // Generic error handling
 showErrorMessage(error.message);
 }
};

Dunning Workflow Components

For subscription businesses, implementing a dunning workflow is essential:

• Email notification within hours of failure
• Inline payment update via billing portal
• Multiple retry attempts over days
• Service pause notice with clear restore path
• Ultimate subscription cancellation if unresolved

Automating the customer communication workflow is essential. When card_velocity_exceeded occurs, trigger an email notification that explains the issue, suggests contacting their bank if they believe this is an error, and provides a direct link to update their payment method. Leveraging our /services/ai-automation expertise can help you build intelligent dunning workflows that recover more revenue automatically.

Error Handling Best Practices

Implementing Robust Error Handling

Effective error handling requires a multi-layered approach that addresses different types of errors with appropriate strategies. Start by categorizing errors based on their type and determining whether they can be resolved automatically through retry logic or require customer intervention.

Key strategies:

1. Graceful degradation: Don't block entire checkout on payment failure
2. Webhook listening: Handle async payment failures (subscription renewals)
3. State preservation: Save progress to resume after payment update
4. Idempotency: Prevent duplicate charges on retry

Use Stripe's webhooks to receive notifications about asynchronous events, including payment failures that occur after the initial checkout process. Webhooks are essential for handling scenarios such as subscription payment failures, where the initial payment succeeds but a subsequent recurring payment fails. Our team has extensive experience implementing webhook-based systems that handle complex payment scenarios reliably.

User Experience Guidelines

The way you communicate errors to customers significantly impacts conversion rates and customer satisfaction:

• Translate technical error codes to user-friendly messages
• Provide multiple resolution paths
• Include support links for complex issues
• Test error flows regularly with test cards

Logging and Monitoring

Implement comprehensive logging:

• Error type, code, message, and parameters
• Customer ID, subscription ID, timestamp
• Geographic and segmentation data

Set up alerts for:

• Sudden error rate increases
• Specific error code spikes
• Recovery rate changes

Testing Error Scenarios

Use Stripe's test card numbers to simulate:

• card_velocity_exceeded
• card_declined
• expired_card
• insufficient_funds
• authentication failures

Verify complete user journey including recovery flows. When testing, verify that your integration correctly identifies the error type and code, displays appropriate user feedback, and triggers any automated workflows. Partnering with our /services/web-development team ensures your payment integration is thoroughly tested and production-ready.

Common Error Codes Reference

Payment-Related Error Codes

Request Validation Errors

Authentication Errors

Rate Limiting

Sources

1. Stripe Error Codes Documentation - Official Stripe documentation covering all API error codes, error types, and handling patterns
2. Stripe Testing Documentation - Official guide for test card numbers and error simulation scenarios
3. Churnkey: Card Velocity Exceeded Decline Code Guide - Comprehensive coverage of the card_velocity_exceeded error code for subscription businesses