Error Handling

Error codes and troubleshooting for Rise B2B API

Error Handling

Rise B2B API returns clear error codes and messages for all endpoints. This guide helps you understand and handle errors effectively in your integrations.

Authentication Errors

Common authentication and authorization issues

API Errors

HTTP status codes and API-specific errors

SDK Errors

SDK-specific error handling and troubleshooting

Best Practices

Error handling best practices and patterns

Common Error Codes

HTTP Status	Description	Common Causes
400	Bad Request	Missing or invalid parameters
401	Unauthorized	Invalid JWT token or SIWE signature
403	Forbidden	Insufficient permissions for the operation
404	Not Found	Resource doesn’t exist
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server-side error

Authentication Errors

SIWE Authentication Errors

Error	Cause	Solution
Rise ID and private key are required	Missing SIWE credentials	Configure RISE_ID and WALLET_PRIVATE_KEY in environment, or use JWT token
Invalid Rise ID address	Incorrect Rise ID format	Ensure Rise ID starts with 0x and is 42 characters
Invalid private key	Incorrect private key format	Ensure private key starts with 0x and is 66 characters
JWT generation failed	Authentication failed	Verify your Rise ID and private key match your Rise account
SIWE error: Invalid signature	Signature verification failed	Verify you’re using the correct wallet and signing the exact message
SIWE error: Expired nonce	Nonce has expired	Retrieve a new SIWE message and sign it immediately

JWT Authentication Errors

Error	Cause	Solution
401 Unauthorized	JWT token expired or invalid	Refresh your JWT token or re-authenticate
Invalid JWT format	Malformed JWT token	Verify JWT token format and ensure it’s complete
JWT signature verification failed	Token has been tampered with	Retrieve a new JWT token from Rise

API Errors

Common API Error Responses

Error	Cause	Solution
401 Unauthorized	Your JWT token has expired	SDK will auto-refresh, or manually refresh token
403 Forbidden	Insufficient permissions	Verify your role permissions for the operation
404 Not Found	Resource doesn’t exist	Verify the nanoid or resource identifier
400 Bad Request	Invalid request parameters	Verify all required fields and parameter formats
429 Too Many Requests	Rate limit exceeded	Implement exponential backoff and retry later

Resource-Specific Errors

Error	Cause	Solution
Team not found	Invalid team nanoid	Verify the team exists and you have access
Company not found	Invalid company nanoid	Verify company permissions and nanoid
User not found	Invalid user nanoid	Verify user exists in your organization
Payment failed	Insufficient balance or invalid parameters	Verify balance and payment parameters
Invalid currency	Unsupported currency code	Use supported currency codes (USD, EUR, etc.)

SDK Error Handling

SDK-Specific Errors

const { RiseApiClient } = require('@riseworks/sdk');

async function handleSDKErrors() {
  try {
    const client = new RiseApiClient({
      environment: 'prod',
      riseIdAuth: {
        riseId: riseId,
        privateKey: walletPrivateKey
      }
    });

    const user = await client.me.get();
    console.log('Success:', user.data);

  } catch (error) {
    // SDK-specific error handling
    if (error.message.includes('Rise ID and private key are required')) {
      console.error('Missing credentials - verify your environment variables');
    } else if (error.message.includes('Invalid Rise ID address')) {
      console.error('Invalid Rise ID format - should be 0x + 40 hex characters');
    } else if (error.message.includes('Invalid private key')) {
      console.error('Invalid private key format - should be 0x + 64 hex characters');
    } else if (error.message.includes('401')) {
      console.error('Authentication failed - verify your credentials');
    } else if (error.message.includes('403')) {
      console.error('Permission denied - verify your role permissions');
    } else if (error.message.includes('404')) {
      console.error('Resource not found - verify the nanoid');
    } else if (error.message.includes('429')) {
      console.error('Rate limit exceeded - implement backoff and retry');
    } else {
      console.error('Unexpected error:', error.message);
    }
  }
}

Automatic Error Handling

The Rise SDK provides automatic error handling for common scenarios:

// SDK automatically handles JWT refresh
    const client = new RiseApiClient({
      riseIdAuth: {
        riseId: riseId,
        privateKey: walletPrivateKey
      }
    });

// If JWT expires, SDK automatically generates a new one
const user = await client.me.get(); // No manual error handling needed

Error Handling Best Practices

Recommended Practices:

• Implement comprehensive error handling for all API calls
• Log errors with context for debugging
• Show user-friendly error messages to end users
• Implement retry logic with exponential backoff for transient errors
• Monitor error rates and set up alerts
• Use SDK error handling when possible

Security Considerations:

• Never ignore errors or catch them silently
• Never show technical error messages to end users
• Never retry indefinitely without backoff
• Never log sensitive information like private keys or JWT tokens
• Never assume errors are always client-side

Retry Logic Example

async function retryWithBackoff(apiCall, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await apiCall();
    } catch (error) {
      if (attempt === maxRetries) {
        throw error; // Final attempt failed
      }

      // Don't retry on client errors (4xx)
      if (error.message.includes('400') ||
          error.message.includes('401') ||
          error.message.includes('403') ||
          error.message.includes('404')) {
        throw error;
      }

      // Exponential backoff: 1s, 2s, 4s
      const delay = Math.pow(2, attempt - 1) * 1000;
      console.log(`Attempt ${attempt} failed, retrying in ${delay}ms...`);
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
}

// Usage
const user = await retryWithBackoff(() => client.me.get());

Monitoring and Debugging

Error Logging

// Structured error logging
function logError(error, context = {}) {
  console.error({
    timestamp: new Date().toISOString(),
    error: error.message,
    status: error.status || 'unknown',
    context,
    stack: error.stack
  });
}

// Usage
try {
  await client.payments.sendPayment(paymentData);
} catch (error) {
  logError(error, {
    operation: 'sendPayment',
    teamId: paymentData.team_nanoid
  });
}

Common Debugging Steps

1. Verify Authentication

   • Verify Rise ID and private key are correct
   • Ensure JWT token is valid and not expired
   • Verify wallet permissions for the Rise account

2. Validate Parameters

   • Verify all required fields are provided
   • Verify nanoid formats are correct
   • Ensure currency codes are supported

3. Verify Permissions

   • Verify your role has permission for the operation
   • Verify team/company access permissions
   • Ensure you’re using the correct Rise account

4. Network Issues

   • Verify internet connectivity
   • Verify API endpoint is accessible
   • Verify rate limiting status

Support Resources

API Reference

Full API specification with error details

Authentication Guide

Authentication troubleshooting

SDK Documentation

SDK error handling examples

Support Email

Get help from our team

Need immediate assistance? Contact our support team at [e-mail] with your error details and we’ll help you resolve the issue quickly.