Stripe Error Codes Reference

Complete reference for error codes you may encounter when using iaptic's Stripe integration.

Error Response Format

All errors follow this format:

interface ErrorResponse {
  status: number;   // HTTP status code
  code: number;     // Error code
  message: string;  // Human-readable message
}

Example:

{
  "status": 403,
  "code": 6778003,
  "message": "Invalid access key"
}

Common Error Codes

Authentication Errors

Code	Status	Message	Description
6778003	403	Invalid access key	Access key is invalid or expired
6778004	401	Invalid API key	API key is missing or invalid
6778005	401	Invalid webhook signature	Webhook signature verification failed

Validation Errors

Code	Status	Message	Description
6778010	400	Invalid payload	Request body is malformed
6778011	400	Missing required field	Required parameter is missing
6778012	400	Invalid offer ID	Offer ID format is incorrect
6778013	400	Invalid subscription ID	Subscription ID not found

Resource Errors

Code	Status	Message	Description
6778020	404	Product not found	Referenced product doesn't exist
6778021	404	Price not found	Referenced price doesn't exist
6778022	404	Subscription not found	Referenced subscription doesn't exist
6778023	404	Customer not found	Referenced customer doesn't exist

Configuration Errors

Code	Status	Message	Description
6778030	400	Stripe not configured	Stripe keys not set in iaptic
6778031	400	Webhook secret missing	Webhook signing secret not configured
6778032	400	Invalid API version	Wrong Stripe API version

Processing Errors

Code	Status	Message	Description
6778040	500	Checkout failed	Failed to create checkout session
6778041	500	Plan change failed	Failed to update subscription
6778042	500	Portal creation failed	Failed to create customer portal
6778043	500	Payment processing error	Payment failed to process

Error Handling Examples

Client-side Error Handling

try {
  await iaptic.createStripeCheckout({/*...*/});
} catch (error) {
  switch (error.code) {
    case 6778003:
      // Handle invalid access key
      localStorage.removeItem('stripe_access_key');
      break;
    case 6778010:
      // Handle invalid payload
      console.error('Invalid request:', error.message);
      break;
    case 6778030:
      // Handle configuration error
      console.error('Stripe not configured');
      break;
    default:
      // Handle unknown error
      console.error('Unknown error:', error);
  }
}

Server-side Error Handling

app.post('/webhook/stripe', async (req, res) => {
  try {
    // Verify webhook signature
    const event = stripe.webhooks.constructEvent(
      req.rawBody,
      req.headers['stripe-signature'],
      webhookSecret
    );
  } catch (error) {
    if (error.code === 6778005) {
      // Invalid webhook signature
      return res.status(401).json({
        status: 401,
        code: 6778005,
        message: 'Invalid webhook signature'
      });
    }
    // Handle other errors
    return res.status(500).json({
      status: 500,
      code: 6778099,
      message: 'Internal server error'
    });
  }
});

Best Practices

1. Error Logging

function logError(error: ErrorResponse) {
  console.error(
    `[${error.code}] ${error.status} ${error.message}`,
    {
      timestamp: new Date().toISOString(),
      code: error.code,
      status: error.status,
      message: error.message
    }
  );
}

2. User-friendly Messages

function getUserMessage(error: ErrorResponse): string {
  switch (error.code) {
    case 6778003:
      return 'Your session has expired. Please log in again.';
    case 6778040:
      return 'Unable to process checkout. Please try again.';
    default:
      return 'An unexpected error occurred. Please try again.';
  }
}

3. Error Recovery

async function handleError(error: ErrorResponse) {
  switch (error.code) {
    case 6778003:
      // Try to refresh access key
      await refreshAccessKey();
      break;
    case 6778040:
      // Retry checkout
      await retryCheckout();
      break;
    case 6778041:
      // Verify subscription status
      await verifySubscription();
      break;
  }
}

4. Error Prevention

function validateRequest(data: any) {
  if (!data.offerId) {
    throw {
      status: 400,
      code: 6778011,
      message: 'Missing required field: offerId'
    };
  }
  if (!data.offerId.startsWith('stripe:')) {
    throw {
      status: 400,
      code: 6778012,
      message: 'Invalid offer ID format'
    };
  }
}