Error Codes

Comprehensive error handling guide for MPPFi - the first neobank infrastructure for AI agents built on Solana blockchain with Machine Payments Protocol.

Error Response Format

All API errors follow this standardized structure:

{
  "error": {
    "type": "invalid_request_error",
    "code": "insufficient_balance",
    "message": "Agent has insufficient balance for this transaction",
    "param": "amount",
    "request_id": "req_abc123xyz",
    "status_code": 400
  }
}

Response Fields:

• type - Error category (see Error Types below)

• code - Specific error code for programmatic handling

• message - Human-readable error description

• param (optional) - Parameter that caused the error

• request_id - Unique request identifier for support

• status_code - HTTP status code

---

Error Types

authentication_error

Authentication failed - invalid or missing API key.

HTTP Status Code: 401

Example Response:

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "Invalid API key provided. Check your API key and try again.",
    "request_id": "req_abc123"
  }
}

Common Causes:

• Missing Authorization header

• Invalid API key format

• Expired or revoked API key

• Using test key in production environment

How to Fix:

// Verify your API key is correctly configured
const mppfi = new MPPFi({
  apiKey: process.env.MPPFI_API_KEY // Ensure this is set
});

// Check environment
if (process.env.NODE_ENV === 'production') {
  // Use production key (mppfi_live_...)
} else {
  // Use test key (mppfi_test_...)
}

---

invalid_request_error

Request is malformed or contains invalid parameters.

HTTP Status Code: 400

Example Response:

{
  "error": {
    "type": "invalid_request_error",
    "code": "missing_required_param",
    "message": "Missing required parameter: agent_id",
    "param": "agent_id",
    "request_id": "req_def456"
  }
}

Common Error Codes:

• missing_required_param - Required field not provided

• invalid_param_value - Parameter value is invalid

• invalid_currency - Unsupported currency (must be USDC)

• invalid_amount - Amount format invalid (must be decimal string)

• invalid_solana_address - Solana address format invalid

How to Fix:

// Validate parameters before calling API
function validatePayment(params) {
  if (!params.agentId) {
    throw new Error('agent_id is required');
  }

  if (!params.amount || parseFloat(params.amount) <= 0) {
    throw new Error('amount must be a positive number');
  }

  if (params.currency !== 'USDC') {
    throw new Error('currency must be USDC');
  }
}

validatePayment(paymentParams);
const payment = await mppfi.payments.create(paymentParams);

---

insufficient_balance_error

Agent account has insufficient USDC balance.

HTTP Status Code: 400

Example Response:

{
  "error": {
    "type": "insufficient_balance_error",
    "code": "insufficient_balance",
    "message": "Agent has insufficient balance. Available: 50.00 USDC, Required: 150.50 USDC",
    "agent_id": "agent_7x8y9z",
    "available_balance": "50.00",
    "required_amount": "150.50",
    "currency": "USDC",
    "request_id": "req_ghi789"
  }
}

How to Fix:

try {
  const payment = await mppfi.payments.create({
    agentId: 'agent_7x8y9z',
    amount: '150.50',
    merchantId: 'merchant_abc123'
  });
} catch (error) {
  if (error instanceof InsufficientBalanceError) {
    console.log(`Need to fund agent. Available: ${error.availableBalance}`);

    // Fund the agent account
    await mppfi.agents.fund('agent_7x8y9z', {
      amount: '500.00',
      source: 'bank_account_xyz'
    });

    // Retry payment
    return await mppfi.payments.create(paymentParams);
  }
}

---

policy_violation_error

Transaction violates agent's on-chain policy rules.

HTTP Status Code: 403

Example Response:

{
  "error": {
    "type": "policy_violation_error",
    "code": "policy_violation",
    "message": "Transaction violates policy: Daily Spending Limit",
    "policy_id": "policy_abc123",
    "policy_name": "Daily Spending Limit",
    "violation_type": "amount_limit_exceeded",
    "details": {
      "rule_type": "amount_limit",
      "max_daily": "5000.00",
      "current_daily_spend": "4800.00",
      "attempted_amount": "500.00"
    },
    "blockchain": {
      "program_address": "MPPFi...Policy123",
      "enforcement": "on_chain"
    },
    "request_id": "req_jkl012"
  }
}

Common Violation Types:

• amount_limit_exceeded - Transaction or daily limit exceeded

• merchant_not_allowed - Merchant not on allowlist

• merchant_blocked - Merchant on blocklist

• time_restriction - Transaction outside allowed hours

• approval_required - Multi-signature approval needed

• velocity_limit_exceeded - Too many transactions in period

How to Fix:

try {
  const payment = await mppfi.payments.create(paymentParams);
} catch (error) {
  if (error instanceof PolicyViolationError) {
    console.log(`Policy violation: ${error.policyName}`);
    console.log(`Violation type: ${error.violationType}`);
    console.log(`Details:`, error.details);

    // Option 1: Adjust transaction to comply
    if (error.violationType === 'amount_limit_exceeded') {
      // Reduce amount or wait until next day
      const maxAllowed = parseFloat(error.details.max_daily) -
                         parseFloat(error.details.current_daily_spend);
      console.log(`Max allowed today: ${maxAllowed}`);
    }

    // Option 2: Update policy if needed
    if (error.violationType === 'merchant_not_allowed') {
      await mppfi.policies.update(error.policyId, {
        rules: [
          {
            type: 'merchant_allowlist',
            allowedMerchants: [...existingMerchants, newMerchantId]
          }
        ]
      });
    }
  }
}

---

rate_limit_error

Too many requests in a short period.

HTTP Status Code: 429

Example Response:

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please retry after 60 seconds.",
    "retry_after": 60,
    "limit": 500,
    "remaining": 0,
    "reset_at": "2026-03-30T15:00:00Z",
    "request_id": "req_mno345"
  }
}

How to Handle:

async function makeRequestWithRetry<T>(
  fn: () => Promise<T>,
  maxRetries = 3
): Promise<T> {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error instanceof RateLimitError) {
        if (i === maxRetries - 1) throw error;

        const delay = (error.retryAfter || Math.pow(2, i)) * 1000;
        console.log(`Rate limited. Retrying after ${delay}ms...`);
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }
      throw error;
    }
  }
}

// Usage
const payment = await makeRequestWithRetry(() =>
  mppfi.payments.create(paymentParams)
);

---

blockchain_error

Solana blockchain transaction failed or is pending.

HTTP Status Code: 500

Example Response:

{
  "error": {
    "type": "blockchain_error",
    "code": "transaction_failed",
    "message": "Solana transaction failed: insufficient SOL for transaction fee",
    "blockchain": {
      "network": "solana",
      "transaction_signature": "5xPq7...3mKt9",
      "error_code": "InsufficientFundsForFee",
      "explorer_url": "https://solscan.io/tx/5xPq7...3mKt9"
    },
    "request_id": "req_pqr678"
  }
}

Common Blockchain Errors:

• transaction_failed - On-chain transaction failed

• transaction_timeout - Transaction didn't confirm in time

• network_congestion - Solana network is congested

• insufficient_sol_for_fee - Not enough SOL for transaction fee

How to Handle:

try {
  const transfer = await mppfi.transfers.create(transferParams);
} catch (error) {
  if (error instanceof BlockchainError) {
    console.log(`Blockchain error: ${error.code}`);
    console.log(`Explorer: ${error.blockchain.explorerUrl}`);

    if (error.code === 'network_congestion') {
      // Retry with higher priority fee
      const transfer = await mppfi.transfers.create({
        ...transferParams,
        priority: 'high'
      });
    } else if (error.code === 'insufficient_sol_for_fee') {
      console.log('MPPFi automatically manages SOL for fees');
      // This should not happen in normal operation
    }
  }
}

---

not_found_error

Requested resource does not exist.

HTTP Status Code: 404

Example Response:

{
  "error": {
    "type": "not_found_error",
    "code": "agent_not_found",
    "message": "No agent account found with ID: agent_xyz",
    "resource_type": "agent",
    "resource_id": "agent_xyz",
    "request_id": "req_stu901"
  }
}

Common Resource Types:

• agent_not_found - Agent account doesn't exist

• payment_not_found - Payment doesn't exist

• policy_not_found - Policy doesn't exist

• merchant_not_found - Merchant doesn't exist

• webhook_not_found - Webhook endpoint doesn't exist

How to Handle:

try {
  const agent = await mppfi.agents.retrieve('agent_xyz');
} catch (error) {
  if (error instanceof NotFoundError) {
    if (error.code === 'agent_not_found') {
      // Create agent if it doesn't exist
      const newAgent = await mppfi.agents.create({
        name: 'New Agent',
        initialBalance: '1000.00'
      });
      return newAgent;
    }
  }
}

---

server_error

Internal server error occurred.

HTTP Status Code: 500, 502, 503

Example Response:

{
  "error": {
    "type": "server_error",
    "code": "internal_error",
    "message": "An internal error occurred. Please try again later.",
    "request_id": "req_vwx234"
  }
}

What to Do:

1. Retry the request with exponential backoff

2. If persistent, check status page: https://status.mppfi.xyz

3. Contact support with request_id

async function retryOnServerError<T>(
  fn: () => Promise<T>,
  maxRetries = 3
): Promise<T> {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error instanceof ServerError && i < maxRetries - 1) {
        const delay = Math.pow(2, i) * 1000;
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }
      throw error;
    }
  }
}

---

Complete Error Code Reference

Authentication Errors (401)

Code	Description	Resolution
invalid_api_key	API key is invalid or malformed	Verify API key format and value
expired_api_key	API key has expired	Generate new API key
revoked_api_key	API key was manually revoked	Create new API key
missing_api_key	No API key provided	Include Authorization header
test_key_in_production	Test key used in production	Use production API key

Request Errors (400)

Code	Description	Resolution
missing_required_param	Required parameter missing	Include required field
invalid_param_value	Parameter value invalid	Check parameter format
invalid_currency	Currency not supported	Use USDC
invalid_amount	Amount format invalid	Use decimal string (e.g., "100.50")
invalid_solana_address	Solana address invalid	Verify address is valid base58
invalid_merchant_id	Merchant ID invalid	Check merchant exists
invalid_policy_rule	Policy rule configuration invalid	Review policy rule structure

Agent Errors

Code	Description	Resolution
agent_not_found	Agent account doesn't exist	Verify agent ID or create agent
agent_suspended	Agent account is suspended	Reactivate agent account
agent_closed	Agent account is closed	Create new agent account
insufficient_balance	Agent has insufficient USDC	Fund agent account
agent_limit_reached	Maximum agents created	Contact support to increase limit

Payment Errors

Code	Description	Resolution
payment_not_found	Payment doesn't exist	Verify payment ID
payment_already_completed	Payment already processed	Check payment status
payment_already_cancelled	Payment already cancelled	Cannot reprocess
payment_failed	Payment execution failed	Check error details and retry
duplicate_idempotency_key	Idempotency key already used	Use unique idempotency key
merchant_not_available	Merchant temporarily unavailable	Retry later
mpp_protocol_error	MPP protocol error	Check MPP parameters

Policy Errors (403)

Code	Description	Resolution
policy_not_found	Policy doesn't exist	Verify policy ID
policy_violation	Transaction violates policy	Adjust transaction or policy
amount_limit_exceeded	Amount limit exceeded	Reduce amount or update policy
merchant_not_allowed	Merchant not on allowlist	Add merchant to allowlist
merchant_blocked	Merchant on blocklist	Remove from blocklist
time_restriction	Outside allowed time window	Wait for allowed time
approval_required	Multi-sig approval needed	Obtain required approvals
velocity_limit_exceeded	Too many transactions	Wait for velocity window reset

Blockchain Errors (500)

Code	Description	Resolution
transaction_failed	On-chain transaction failed	Check blockchain explorer
transaction_timeout	Transaction didn't confirm	Retry transaction
network_congestion	Solana network congested	Retry with higher priority
insufficient_sol_for_fee	Not enough SOL for fees	Contact support (should auto-manage)
invalid_transaction	Transaction structure invalid	Contact support

Webhook Errors

Code	Description	Resolution
webhook_not_found	Webhook doesn't exist	Verify webhook ID
webhook_delivery_failed	Failed to deliver event	Check endpoint availability
invalid_webhook_signature	Signature verification failed	Check signing secret
webhook_url_invalid	Webhook URL invalid	Provide valid HTTPS URL

---

SDK Error Handling Examples

TypeScript

import {
  MPPFiError,
  InsufficientBalanceError,
  PolicyViolationError,
  AuthenticationError,
  RateLimitError,
  BlockchainError,
  NotFoundError,
  ServerError
} from '@mppfi/node';

async function handlePayment(paymentParams) {
  try {
    const payment = await mppfi.payments.create(paymentParams);
    console.log(`Payment successful: ${payment.id}`);
    return payment;
  } catch (error) {
    // Handle specific error types
    if (error instanceof InsufficientBalanceError) {
      console.error('Insufficient balance');
      console.error(`Available: ${error.availableBalance}`);
      console.error(`Required: ${error.requiredAmount}`);
      // Fund agent and retry
    } else if (error instanceof PolicyViolationError) {
      console.error(`Policy violation: ${error.policyName}`);
      console.error(`Violation: ${error.violationType}`);
      console.error(`Details:`, error.details);
      // Handle policy violation
    } else if (error instanceof BlockchainError) {
      console.error(`Blockchain error: ${error.code}`);
      console.error(`Explorer: ${error.blockchain.explorerUrl}`);
      // Check transaction on explorer
    } else if (error instanceof AuthenticationError) {
      console.error('Authentication failed - check API key');
      // Fix API key configuration
    } else if (error instanceof RateLimitError) {
      console.error(`Rate limited - retry after ${error.retryAfter}s`);
      // Implement retry with backoff
    } else if (error instanceof NotFoundError) {
      console.error(`Resource not found: ${error.resourceType}`);
      // Create resource or fix ID
    } else if (error instanceof ServerError) {
      console.error('Server error - retrying...');
      // Retry with exponential backoff
    } else if (error instanceof MPPFiError) {
      console.error(`MPPFi error: ${error.message}`);
      console.error(`Request ID: ${error.requestId}`);
      // Generic MPPFi error handling
    } else {
      console.error('Unexpected error:', error);
      // Handle unexpected errors
    }
  }
}

Python

from mppfi.errors import (
    MPPFiError,
    InsufficientBalanceError,
    PolicyViolationError,
    AuthenticationError,
    RateLimitError,
    BlockchainError,
    NotFoundError,
    ServerError
)

def handle_payment(payment_params):
    try:
        payment = mppfi.payments.create(**payment_params)
        print(f"Payment successful: {payment.id}")
        return payment
    except InsufficientBalanceError as e:
        print(f"Insufficient balance")
        print(f"Available: {e.available_balance}")
        print(f"Required: {e.required_amount}")
        # Fund agent and retry
    except PolicyViolationError as e:
        print(f"Policy violation: {e.policy_name}")
        print(f"Violation: {e.violation_type}")
        print(f"Details: {e.details}")
        # Handle policy violation
    except BlockchainError as e:
        print(f"Blockchain error: {e.code}")
        print(f"Explorer: {e.blockchain['explorer_url']}")
        # Check transaction on explorer
    except AuthenticationError:
        print("Authentication failed - check API key")
        # Fix API key configuration
    except RateLimitError as e:
        print(f"Rate limited - retry after {e.retry_after}s")
        # Implement retry with backoff
    except NotFoundError as e:
        print(f"Resource not found: {e.resource_type}")
        # Create resource or fix ID
    except ServerError:
        print("Server error - retrying...")
        # Retry with exponential backoff
    except MPPFiError as e:
        print(f"MPPFi error: {e.message}")
        print(f"Request ID: {e.request_id}")
        # Generic MPPFi error handling
    except Exception as e:
        print(f"Unexpected error: {e}")
        # Handle unexpected errors

Rust

use mppfi::errors::{MPPFiError, ErrorType};

async fn handle_payment(params: PaymentCreateParams) -> Result<Payment, MPPFiError> {
    match mppfi.payments().create(params).await {
        Ok(payment) => {
            println!("Payment successful: {}", payment.id);
            Ok(payment)
        }
        Err(e) => match e {
            MPPFiError::InsufficientBalance {
                available_balance,
                required_amount,
                ..
            } => {
                eprintln!("Insufficient balance");
                eprintln!("Available: {}", available_balance);
                eprintln!("Required: {}", required_amount);
                // Fund agent and retry
                Err(e)
            }
            MPPFiError::PolicyViolation {
                policy_name,
                violation_type,
                details,
                ..
            } => {
                eprintln!("Policy violation: {}", policy_name);
                eprintln!("Violation: {}", violation_type);
                eprintln!("Details: {:?}", details);
                // Handle policy violation
                Err(e)
            }
            MPPFiError::Blockchain { code, explorer_url, .. } => {
                eprintln!("Blockchain error: {}", code);
                eprintln!("Explorer: {}", explorer_url);
                // Check transaction on explorer
                Err(e)
            }
            MPPFiError::Authentication { .. } => {
                eprintln!("Authentication failed - check API key");
                // Fix API key configuration
                Err(e)
            }
            MPPFiError::RateLimit { retry_after, .. } => {
                eprintln!("Rate limited - retry after {}s", retry_after);
                // Implement retry with backoff
                Err(e)
            }
            MPPFiError::NotFound { resource_type, .. } => {
                eprintln!("Resource not found: {}", resource_type);
                // Create resource or fix ID
                Err(e)
            }
            MPPFiError::Server { request_id, .. } => {
                eprintln!("Server error - retrying...");
                eprintln!("Request ID: {}", request_id);
                // Retry with exponential backoff
                Err(e)
            }
            _ => {
                eprintln!("Unexpected error: {}", e);
                Err(e)
            }
        },
    }
}

Go

func handlePayment(params *mppfi.PaymentCreateParams) (*mppfi.Payment, error) {
    payment, err := client.Payments.Create(params)
    if err != nil {
        switch e := err.(type) {
        case *mppfi.InsufficientBalanceError:
            log.Printf("Insufficient balance")
            log.Printf("Available: %s", e.AvailableBalance)
            log.Printf("Required: %s", e.RequiredAmount)
            // Fund agent and retry
        case *mppfi.PolicyViolationError:
            log.Printf("Policy violation: %s", e.PolicyName)
            log.Printf("Violation: %s", e.ViolationType)
            log.Printf("Details: %+v", e.Details)
            // Handle policy violation
        case *mppfi.BlockchainError:
            log.Printf("Blockchain error: %s", e.Code)
            log.Printf("Explorer: %s", e.ExplorerURL)
            // Check transaction on explorer
        case *mppfi.AuthenticationError:
            log.Println("Authentication failed - check API key")
            // Fix API key configuration
        case *mppfi.RateLimitError:
            log.Printf("Rate limited - retry after %d seconds", e.RetryAfter)
            // Implement retry with backoff
        case *mppfi.NotFoundError:
            log.Printf("Resource not found: %s", e.ResourceType)
            // Create resource or fix ID
        case *mppfi.ServerError:
            log.Println("Server error - retrying...")
            log.Printf("Request ID: %s", e.RequestID)
            // Retry with exponential backoff
        default:
            log.Printf("Unexpected error: %v", err)
        }
        return nil, err
    }

    log.Printf("Payment successful: %s", payment.ID)
    return payment, nil
}

---

Best Practices

1. Always Handle Errors Explicitly

// Bad - unhandled promise rejection
const payment = await mppfi.payments.create(params);

// Good - explicit error handling
try {
  const payment = await mppfi.payments.create(params);
  console.log('Payment successful');
} catch (error) {
  console.error('Payment failed:', error);
  // Handle error appropriately
}

2. Use Type-Specific Error Handlers

// Specific handling for different error types
try {
  const payment = await mppfi.payments.create(params);
} catch (error) {
  if (error instanceof InsufficientBalanceError) {
    // Handle insufficient balance
    await fundAgentAccount();
  } else if (error instanceof PolicyViolationError) {
    // Handle policy violation
    await updatePolicy();
  } else {
    // Handle other errors
    throw error;
  }
}

3. Log Request IDs for Support

try {
  const payment = await mppfi.payments.create(params);
} catch (error) {
  logger.error('Payment failed', {
    requestId: error.requestId,
    errorCode: error.code,
    errorType: error.type,
    message: error.message
  });
  // Include request_id when contacting support
}

4. Implement Retry Logic for Transient Errors

async function retryWithBackoff<T>(
  fn: () => Promise<T>,
  maxRetries = 3,
  baseDelay = 1000
): Promise<T> {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      const isRetryable =
        error instanceof RateLimitError ||
        error instanceof ServerError ||
        error instanceof BlockchainError;

      if (!isRetryable || i === maxRetries - 1) {
        throw error;
      }

      const delay = error.retryAfter
        ? error.retryAfter * 1000
        : baseDelay * Math.pow(2, i);

      console.log(`Retry ${i + 1}/${maxRetries} after ${delay}ms`);
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
}

// Usage
const payment = await retryWithBackoff(() =>
  mppfi.payments.create(params)
);

5. Validate Before API Calls

function validatePaymentParams(params) {
  if (!params.agentId) {
    throw new Error('agent_id is required');
  }

  const amount = parseFloat(params.amount);
  if (isNaN(amount) || amount <= 0) {
    throw new Error('amount must be a positive number');
  }

  if (params.currency !== 'USDC') {
    throw new Error('currency must be USDC');
  }

  if (!params.merchantId) {
    throw new Error('merchant_id is required');
  }
}

// Validate before calling API
validatePaymentParams(params);
const payment = await mppfi.payments.create(params);

---

Monitoring and Alerting

Track Error Rates

class ErrorMetrics {
  private counts: Map<string, number> = new Map();

  track(error: MPPFiError) {
    const key = `${error.type}:${error.code}`;
    this.counts.set(key, (this.counts.get(key) || 0) + 1);
  }

  getTopErrors(limit = 10) {
    return Array.from(this.counts.entries())
      .sort((a, b) => b[1] - a[1])
      .slice(0, limit);
  }

  getErrorRate(totalRequests: number) {
    const totalErrors = Array.from(this.counts.values())
      .reduce((sum, count) => sum + count, 0);
    return totalErrors / totalRequests;
  }
}

const metrics = new ErrorMetrics();

try {
  await mppfi.payments.create(params);
} catch (error) {
  metrics.track(error);
  throw error;
}

Alert on Critical Errors

async function monitorErrors() {
  const errorRate = await getErrorRate('1h');

  if (errorRate > 0.05) { // 5% error rate
    await sendAlert({
      severity: 'high',
      message: `Error rate at ${(errorRate * 100).toFixed(2)}%`,
      threshold: '5%'
    });
  }
}

---

Getting Help

If you encounter persistent errors:

1. Check Status Page: https://status.mppfi.xyz

2. Review Documentation: https://docs.mppfi.xyz

3. Search Known Issues: https://github.com/mppfi/issues

4. Contact Support: [email protected]

   • Include request_id from error response

   • Describe steps to reproduce

   • Include relevant code snippets

   • Mention SDK version and environment

---

Next Steps

• API Reference - Complete REST API documentation

• SDK Documentation - Language-specific SDK guides

• Quickstart Guide - Get started in 5 minutes

• Webhooks - Real-time event notifications

• Policies - On-chain policy enforcement