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/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

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
Validate Parameters
- Verify all required fields are provided
- Verify nanoid formats are correct
- Ensure currency codes are supported
Verify Permissions
- Verify your role has permission for the operation
- Verify team/company access permissions
- Ensure you’re using the correct Rise account
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 Hello@Riseworks.io with your error details and we’ll help you resolve the issue quickly.

Getting Started

Advanced

Error Handling

Error Handling

Authentication Errors

API Errors

SDK Errors

Best Practices

Common Error Codes

Authentication Errors

SIWE Authentication Errors

JWT Authentication Errors

API Errors

Common API Error Responses

Resource-Specific Errors

SDK Error Handling

SDK-Specific Errors

Automatic Error Handling

Error Handling Best Practices

Recommended Practices:

Security Considerations:

Retry Logic Example

Monitoring and Debugging

Error Logging

Common Debugging Steps

Support Resources

API Reference

Authentication Guide

SDK Documentation

Support Email

​Error Handling

Authentication Errors

API Errors

SDK Errors

Best Practices

​Common Error Codes

​Authentication Errors

​SIWE Authentication Errors

​JWT Authentication Errors

​API Errors

​Common API Error Responses

​Resource-Specific Errors

​SDK Error Handling

​SDK-Specific Errors

​Automatic Error Handling

​Error Handling Best Practices

​Recommended Practices:

​Security Considerations:

​Retry Logic Example

​Monitoring and Debugging

​Error Logging

​Common Debugging Steps

​Support Resources

API Reference

Authentication Guide

SDK Documentation

Support Email

Error Handling

Common Error Codes

Authentication Errors

SIWE Authentication Errors

JWT Authentication Errors

API Errors

Common API Error Responses

Resource-Specific Errors

SDK Error Handling

SDK-Specific Errors

Automatic Error Handling

Error Handling Best Practices

Recommended Practices:

Security Considerations:

Retry Logic Example

Monitoring and Debugging

Error Logging

Common Debugging Steps

Support Resources