Error Codes Reference

This page provides a comprehensive reference of all error codes returned by the VesuvioPay SDK API.

Quick Reference

For detailed error handling strategies, see the Error Handling guide.

Error Code Categories

Customer Errors

Error Code	HTTP Status	Description	Resolution
`CUSTOMER_NOT_FOUND`	404	Customer with the specified identifier was not found	Verify the customer ID is correct and belongs to your store
`CUSTOMER_ALREADY_DELETED`	409	The customer has already been deleted	This is an idempotent operation; the customer is already removed
`CUSTOMER_PROFILE_UPDATE_FAILED`	500	Customer profile update operation failed	Retry the operation; contact support if the issue persists

Address Errors

Error Code	HTTP Status	Description	Resolution
`ADDRESS_NOT_FOUND`	404	Address with the specified ID was not found	Verify the address ID is correct and belongs to the customer
`ADDRESS_CREATION_FAILED`	500	Failed to create new address	Check address data validation; retry the operation
`ADDRESS_UPDATE_FAILED`	500	Failed to update the address	Verify address data; retry the operation
`ADDRESS_DELETION_FAILED`	500	Failed to delete the address	Retry the operation; check if address is in use
`INVALID_ADDRESS_DATA`	400	Address data is invalid or incomplete	Review validation errors in the response

Authentication & Authorization Errors

Error Code	HTTP Status	Description	Resolution
`INVALID_TOKEN`	401	JWT token is invalid or malformed	Refresh the authentication token
`TOKEN_EXPIRED`	401	JWT token has expired	Obtain a new token through authentication
`ACCESS_DENIED`	403	Insufficient permissions for this operation	Verify you have the required permissions
`INVALID_CREDENTIALS`	401	Login credentials are incorrect	Verify username and password
`USER_NOT_FOUND`	404	User account not found	Verify the user exists; may need to register
`USER_ALREADY_EXISTS`	409	User with this email/phone already exists	Use a different email/phone or login instead
`REGISTRATION_INCOMPLETE`	400	User registration is not complete	Complete all registration steps
`AUTHENTICATION_FAILED`	401	Authentication process failed	Retry authentication; verify credentials
`SOCIAL_AUTH_FAILED`	401	Social authentication (OAuth) failed	Retry social login; check provider status
`COMPANY_SETUP_FAILED`	500	Failed to set up company during registration	Contact support for assistance

API Key Errors

Error Code	HTTP Status	Description	Resolution
`API_KEY_NOT_FOUND`	404	API key not found in the system	Verify the API key ID is correct
`INVALID_API_KEY`	401	API key is invalid or malformed	Check the `X-API-Key` header value
`API_KEY_INACTIVE`	401	API key has been revoked or deactivated	Generate a new API key
`API_KEY_EXPIRED`	401	API key has expired	Generate a new API key
`API_KEY_CREATION_FAILED`	500	Failed to create new API key	Retry the operation; contact support if needed
`API_KEY_UPDATE_FAILED`	500	Failed to update API key settings	Retry the operation
`API_KEY_ROTATION_FAILED`	500	Failed to rotate API key	Retry rotation; use manual key generation if needed
`API_KEY_REVOCATION_FAILED`	500	Failed to revoke API key	Retry revocation; contact support if urgent
`NO_STORE_ACCESS`	403	API key does not have access to the specified store	Use the correct API key for this store

Email & Phone Errors

Error Code	HTTP Status	Description	Resolution
`EMAIL_ALREADY_IN_USE`	409	Email address is already registered	Use a different email or login instead
`EMAIL_VERIFICATION_FAILED`	400	Email verification failed	Request a new verification code
`EMAIL_CHANGE_NOT_AVAILABLE`	400	Email change is not available at this time	Contact support for assistance
`EMAIL_CHANGE_FAILED`	500	Failed to change email address	Retry the operation
`PHONE_ALREADY_IN_USE`	409	Phone number is already registered	Use a different phone or login instead
`PHONE_VERIFICATION_FAILED`	400	Phone verification failed	Request a new verification code
`PHONE_CHANGE_NOT_AVAILABLE`	400	Phone change is not available at this time	Contact support for assistance
`INVALID_PHONE_FORMAT`	400	Phone number format is invalid	Use E.164 format (e.g., +1234567890)
`PHONE_CHANGE_FAILED`	500	Failed to change phone number	Retry the operation

Payment Errors

Error Code	HTTP Status	Description	Resolution
`PAYMENT_GATEWAY_ERROR`	502	Payment gateway returned an error	Retry the payment; check gateway status
`PAYMENT_METHOD_NOT_FOUND`	404	Payment method not found	Verify payment method ID
`PAYMENT_METHOD_CREATION_FAILED`	500	Failed to create payment method	Retry with valid card details
`PAYMENT_PROCESSING_FAILED`	402	Payment processing failed	Check card details; ensure sufficient funds
`PAYMENT_INTENT_CREATION_FAILED`	500	Failed to create payment intent	Retry the operation
`PAYMENT_INTENT_CONFIRMATION_FAILED`	402	Failed to confirm payment intent	Verify payment details; retry
`TRANSFER_CREATION_FAILED`	500	Failed to create transfer to merchant	Contact support for assistance
`WEBHOOK_VALIDATION_FAILED`	400	Webhook signature validation failed	Verify webhook secret is correct

Payment Account Errors

Error Code	HTTP Status	Description	Resolution
`PAYMENT_ACCOUNT_NOT_FOUND`	404	Payment account not found	Verify account ID; complete onboarding
`PAYMENT_ACCOUNT_CREATION_FAILED`	500	Failed to create payment account	Retry; verify business details
`PAYMENT_ACCOUNT_UPDATE_FAILED`	500	Failed to update payment account	Retry; verify update data
`EXTERNAL_ACCOUNT_ID_MISSING`	400	External payment account ID is missing	Complete payment account setup

Card & Bank Account Errors

Error Code	HTTP Status	Description	Resolution
`BANK_ACCOUNT_NOT_FOUND`	404	Bank account not found	Verify bank account ID
`BANK_ACCOUNT_CREATION_FAILED`	500	Failed to create bank account	Verify bank account details; retry
`BANK_ACCOUNT_DELETION_FAILED`	500	Failed to delete bank account	Retry; check if account is in use
`CANNOT_DELETE_DEFAULT_BANK_ACCOUNT`	409	Cannot delete the default bank account	Set another account as default first
`BANK_ACCOUNT_SYNC_FAILED`	500	Failed to sync bank accounts from payment provider	Retry sync; check provider connection
`CARD_NOT_FOUND`	404	Card not found	Verify card ID
`CARD_CREATION_FAILED`	500	Failed to create card	Verify card details; retry
`CARD_DELETION_FAILED`	500	Failed to delete card	Retry; check if card is in use
`CANNOT_DELETE_DEFAULT_CARD`	409	Cannot delete the default card	Set another card as default first
`CARD_SYNC_FAILED`	500	Failed to sync cards from payment provider	Retry sync; check provider connection
`SET_DEFAULT_CARD_FAILED`	500	Failed to set card as default	Retry the operation
`STRIPE_CUSTOMER_CREATION_FAILED`	500	Failed to create Stripe customer	Retry; contact support if issue persists

Cart & Checkout Errors

Error Code	HTTP Status	Description	Resolution
`CHECKOUT_NOT_FOUND`	404	Checkout session not found	Verify checkout ID; session may have expired
`CHECKOUT_CREATION_FAILED`	500	Failed to create checkout session	Retry; verify cart has items
`CHECKOUT_INVALID_STATE`	400	Checkout is in an invalid state for this operation	Verify checkout status; may need to restart
`CART_NOT_FOUND`	404	Cart not found for the customer	Cart may be empty or expired
`EMPTY_CART`	400	Cart is empty; cannot proceed to checkout	Add items to cart before checkout
`INSUFFICIENT_PAYMENT_METHODS`	400	No valid payment methods available	Add a payment method before checkout

Product & Inventory Errors

Error Code	HTTP Status	Description	Resolution
`INSUFFICIENT_INVENTORY`	409	Not enough inventory for the requested quantity	Reduce quantity or check availability
`PRODUCT_OUT_OF_STOCK`	409	Product is out of stock	Subscribe to back-in-stock notifications
`INVENTORY_LIMIT_EXCEEDED`	400	Requested quantity exceeds inventory limits	Reduce quantity to available stock
`PRODUCT_NOT_FOUND`	404	Product not found	Verify product ID or external ID
`PRODUCT_VARIANT_NOT_FOUND`	404	Product variant not found	Verify variant ID or external variant ID

Order Errors

Error Code	HTTP Status	Description	Resolution
`ORDER_NOT_FOUND`	404	Order not found	Verify order ID or external order ID

Subscription & Invoice Errors

Error Code	HTTP Status	Description	Resolution
`SUBSCRIPTION_NOT_FOUND`	404	Subscription not found	Verify subscription ID
`PLAN_NOT_FOUND`	404	Subscription plan not found	Verify plan ID
`INVOICE_NOT_FOUND`	404	Invoice not found	Verify invoice ID
`INVOICE_NOT_PAID`	402	Invoice has not been paid	Pay the invoice to proceed
`INVOICE_DOWNLOAD_FAILED`	500	Failed to download invoice	Retry; contact support if issue persists

File Upload Errors

Error Code	HTTP Status	Description	Resolution
`FILE_NOT_PROVIDED`	400	No file was provided in the request	Include a file in the upload request
`FILE_SIZE_EXCEEDED`	400	File size exceeds maximum allowed	Reduce file size (max 10MB)
`INVALID_FILE_FORMAT`	400	File format is not supported	Use supported formats (JPEG, PNG, PDF)
`INVALID_CONTENT_TYPE`	400	File content type is invalid	Ensure content type matches file format
`FILE_UPLOAD_FAILED`	500	File upload failed	Retry the upload

SMS & Template Errors

Error Code	HTTP Status	Description	Resolution
`SMS_NOT_FOUND`	404	SMS message not found	Verify SMS ID
`TWILIO_SETTINGS_NOT_FOUND`	404	Twilio settings not configured	Configure Twilio in admin panel
`TEMPLATE_TYPE_NOT_FOUND`	404	SMS template type not found	Verify template type
`TEMPLATE_WORD_NOT_FOUND`	404	Template word/variable not found	Verify template variable names
`TEMPLATE_NOT_FOUND`	404	SMS template not found	Verify template ID
`TEMPLATE_CREATION_FAILED`	500	Failed to create SMS template	Retry; verify template data
`TEMPLATE_UPDATE_FAILED`	500	Failed to update SMS template	Retry the operation
`TEMPLATE_DELETION_FAILED`	500	Failed to delete SMS template	Retry; check if template is in use
`TEMPLATE_IN_USE`	409	Template is in use and cannot be deleted	Deactivate template or replace references

Platform & Store Errors

Error Code	HTTP Status	Description	Resolution
`PLATFORM_NOT_FOUND`	404	External platform not found	Verify platform ID
`STORE_NOT_FOUND`	404	Store not found	Verify store ID
`COMPANY_NOT_FOUND`	404	Company not found	Verify company ID

General Errors

Error Code	HTTP Status	Description	Resolution
`VALIDATION_FAILED`	400	Request validation failed	Review validation errors in response
`INVALID_INPUT`	400	Input data is invalid	Check request format and required fields
`INVALID_OPERATION`	400	Operation is not valid in current context	Verify operation prerequisites
`INVALID_ENTITY_TYPE`	400	Entity type is invalid	Use a supported entity type
`INVALID_PREFIX`	400	ID prefix is invalid	Use correct ID format for entity type
`STORE_ID_REQUIRED`	400	Store ID is required for this operation	Include store ID in request
`RESOURCE_NOT_FOUND`	404	Requested resource was not found	Verify resource ID and permissions
`DUPLICATE_RESOURCE`	409	Resource with this identifier already exists	Use update instead or change identifier
`INTERNAL_ERROR`	500	An internal error occurred	Retry; contact support if issue persists
`INTERNAL_SERVER_ERROR`	500	Internal server error	Retry; contact support if issue persists
`SERVICE_UNAVAILABLE`	503	Service is temporarily unavailable	Retry with exponential backoff
`TIMEOUT`	408	Request timeout	Retry the operation
`HTTP_REQUEST_FAILED`	502	External HTTP request failed	Retry; check external service status

Using Error Codes

Example Error Response

{
  "success": false,
  "message": "Product with this ID was not found in your store",
  "errorCode": "PRODUCT_NOT_FOUND"
}

Example with Validation Errors

{
  "success": false,
  "message": "Request validation failed",
  "errorCode": "VALIDATION_FAILED",
  "errors": [
    {
      "field": "email",
      "message": "Email address is required"
    },
    {
      "field": "phoneNumber",
      "message": "Phone number must be in E.164 format"
    }
  ]
}

Error Handling Best Practices

Always check the errorCode field for programmatic error handling
Use the message field for logging and debugging
Show the message field to users only after sanitizing for security
Implement retry logic for 5xx errors with exponential backoff
Don't retry 4xx errors (except 429) - they require client-side fixes

For comprehensive error handling strategies, see the Error Handling Guide.

Error Handling Guide - Comprehensive error handling strategies
Rate Limiting - Understanding and handling rate limits
Authentication - Authentication and authorization errors

Quick Reference​

Error Code Categories​

Customer Errors​

Address Errors​

Authentication & Authorization Errors​

API Key Errors​

Email & Phone Errors​

Payment Errors​

Payment Account Errors​

Card & Bank Account Errors​

Cart & Checkout Errors​

Product & Inventory Errors​

Order Errors​

Subscription & Invoice Errors​

File Upload Errors​

SMS & Template Errors​

Platform & Store Errors​

General Errors​

Using Error Codes​

Example Error Response​

Example with Validation Errors​

Error Handling Best Practices​

Related Documentation​