Menu

Navigation

Getting Started

Configuration

Routes

Rate Limiters

Early Access

Troubleshooting

Common issues and solutions when working with ApiCharge

Troubleshooting ApiCharge

This guide provides solutions for common issues you might encounter when working with ApiCharge, along with diagnostic steps and resolution strategies.

Error Code Reference

ApiCharge uses standardized error codes to communicate issues. Here are the currently implemented error codes:

Error Code Description Common Causes
EX001 The pricing strategy configuration is invalid or not supported Invalid quote configuration, missing pricing parameters
EX002 The globals configuration is invalid Missing or incorrect GlobalSettings in appsettings.json
EX003 The smart contract network access key or passphrase is missing or invalid Missing APICHARGE_SIGNING_KEY or APICHARGE_NETWORK_PASSPHRASE environment variables
EX004 The unix timestamp must be positive Invalid timestamp values in requests, clock synchronization issues
EX005 Account information could not be retrieved from the Stellar Payment Platform Stellar RPC connectivity issues, invalid account configuration
EX006 Failed to generate quote for API usage Invalid route configuration, missing quote definitions
EX007 Invalid purchase instruction parameters Malformed purchase request, invalid client key or quote
EX008 Failed to simulate transaction on the Stellar Payment Platform Stellar network issues, insufficient funds, invalid transaction
EX009 Failed to execute Stellar Payment Platform transaction Network connectivity, insufficient funds, transaction rejection
EX010 Transaction processing timeout - operation did not complete within allocated time Network congestion, slow Stellar Payment Platform confirmation
EX011 Invalid route configuration Missing or malformed route definitions in configuration
EX012 Failed to retrieve routes from proxy configuration YARP configuration issues, missing route mappings
EX013 Missing account identifier or route quote Incomplete purchase request, missing required fields
EX014 Server configuration error - environment variables missing Missing critical environment variables like signing keys
EX015 Invalid transaction format or signature Malformed Stellar Payment Platform transaction, signature verification failure
EX016 Error creating or loading rate limiter resources Redis connectivity issues, rate limiter initialization problems
EX017 Error in rate limiting middleware Rate limiter execution failure, middleware configuration issues
EX018 Stream operation failed due to rate limiting or token expiration Streaming connections exceeding rate limits or expired tokens
EX019 HTTP upgrade operation failed WebSocket or HTTP/2 upgrade issues
EX020 Invalid certificate validation SSL/TLS certificate issues, trust validation problems

Common Issues

Service fails to start with configuration errors +

Symptoms:

  • Application crashes on startup
  • Configuration validation errors in logs
  • Missing environment variable warnings

Common Causes:

  • Missing APICHARGE_SIGNING_KEY environment variable
  • Missing APICHARGE_NETWORK_PASSPHRASE environment variable
  • Invalid JSON syntax in appsettings.json
  • Incorrect GlobalSettings configuration

Resolution Steps:

  1. Verify all required environment variables are set: 
    echo $APICHARGE_SIGNING_KEY
echo $APICHARGE_NETWORK_PASSPHRASE
  2. Validate JSON syntax in configuration files using a JSON validator
  3. Check the application logs for specific error messages
  4. Ensure the signing key is a valid Stellar secret key (starts with 'S')
  5. Verify the network passphrase matches your selected network (Testnet/Mainnet)
Stellar Payment Platform connectivity issues +

Symptoms:

  • Failed to retrieve account information (EX005)
  • Transaction simulation failures (EX008)
  • Transaction execution timeouts (EX010)

Resolution Steps:

  1. Check Stellar RPC server connectivity: 
    curl -X POST https://soroban-testnet.stellar.org/soroban/rpc \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getHealth"}'
  2. Verify your Stellar account exists and has funds
  3. Check network connectivity and firewall settings
  4. Ensure the StellarEndpointRPC setting matches your chosen network
  5. Monitor Stellar Payment Platform status for any known issues
Rate limiting issues +

Symptoms:

  • Rate limiter creation errors (EX016)
  • Rate limiting middleware failures (EX017)
  • Stream operation failures (EX018)

Resolution Steps:

  1. Check Redis connectivity if using distributed rate limiting
  2. Verify rate limiter configuration in quotes
  3. Check for clock synchronization issues between client and server
  4. Review token validity and expiration times
  5. Ensure proper session affinity for streaming connections in clustered deployments
Quote and purchase issues +

Symptoms:

  • Failed to generate quotes (EX006)
  • Invalid purchase instructions (EX007)
  • Missing account or quote information (EX013)

Resolution Steps:

  1. Verify route configuration includes proper quote definitions
  2. Check that ApiChargeQuotes section is properly configured
  3. Ensure client provides valid Stellar public key
  4. Verify quote hasn't expired before attempting purchase
  5. Check that all required fields are included in purchase requests
SSL/TLS and certificate issues +

Symptoms:

  • Certificate validation errors (EX020)
  • HTTPS connection failures
  • Trust validation problems

Resolution Steps:

  1. Verify certificate file paths and permissions
  2. Check certificate expiration dates
  3. Ensure certificate matches the domain being used
  4. Review AllowSelfSignedServerCertificates setting for development
  5. Check AllowedServerCertificateThumbprints for custom certificates

Diagnostic Tools

Health Check Endpoints

ApiCharge provides health check endpoints to verify system status:

# Basic health check
curl http://localhost:5000/health

# Detailed health information
curl http://localhost:5000/health/ready

Logging

Enable detailed logging for troubleshooting by adjusting log levels in appsettings.json:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "ApiChargePrototype": "Debug",
      "Microsoft.AspNetCore": "Warning"
    }
  }
}

Getting Help

If you continue to experience issues after following these troubleshooting steps:

Next Steps

Related documentation that may help with troubleshooting: