Skip to main content
StateSet uses conventional HTTP response codes and provides detailed error messages to help you quickly identify and resolve issues.

​
🚨 Error Response Format

All errors follow a consistent JSON structure: 
{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "The 'amount' parameter is required but was not provided",
    "param": "amount",
    "doc_url": "https://docs.stateset.com/errors/parameter_missing",
    "request_id": "req_1234567890abcdef"
  }
}

​
Error Object Fields

FieldTypeDescription
typestringThe type of error returned
codestringA short string identifying the error
messagestringA human-readable message providing details
paramstringThe parameter related to the error (if applicable)
doc_urlstringLink to relevant documentation
request_idstringUnique identifier for this request

​
📊 HTTP Status Codes

  • 2xx Success
  • 4xx Client Errors
  • 5xx Server Errors
CodeMeaningDescription
200OKRequest succeeded
201CreatedResource successfully created
202AcceptedRequest accepted for processing
204No ContentRequest succeeded with no response body

​
🔍 Error Types

​
Authentication Errors

Occur when API keys are missing, invalid, or lack permissions. 
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "The provided API key is invalid",
    "request_id": "req_abc123"
  }
}
  • api_key_missing - No API key provided
  • invalid_api_key - API key is malformed or doesn’t exist
  • api_key_expired - API key has expired
  • api_key_revoked - API key has been revoked
  • insufficient_permissions - API key lacks required permissions

​
Invalid Request Errors

Occur when request parameters are invalid or missing. 
{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "Amount must be a positive number",
    "param": "amount",
    "request_id": "req_def456"
  }
}
  • parameter_missing - Required parameter not provided
  • parameter_invalid - Parameter value is invalid
  • parameter_unknown - Unknown parameter provided
  • request_invalid - Request body is malformed
  • idempotency_key_in_use - Idempotency key already used

​
Rate Limit Errors

Occur when you exceed API rate limits. 
{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Please retry after 60 seconds",
    "request_id": "req_ghi789"
  }
}
Response headers include: 
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1640995200
Retry-After: 60

​
API Errors

Occur due to problems on StateSet’s servers. 
{
  "error": {
    "type": "api_error",
    "code": "internal_server_error",
    "message": "An unexpected error occurred. Please try again",
    "request_id": "req_jkl012"
  }
}

​
💻 Error Handling Examples

const { StateSet } = require('@stateset/sdk');

const stateset = new StateSet({
  apiKey: process.env.STATESET_API_KEY
});

async function makePayment(amount, recipient) {
  try {
    const payment = await stateset.payments.create({
      amount,
      recipient,
      currency: 'ssusd'
    });
    return payment;
  } catch (error) {
    // Handle different error types
    switch (error.type) {
      case 'authentication_error':
        console.error('Authentication failed:', error.message);
        // Refresh API key or prompt for authentication
        break;
        
      case 'invalid_request_error':
        console.error('Invalid request:', error.message);
        if (error.param) {
          console.error('Problem with parameter:', error.param);
        }
        break;
        
      case 'rate_limit_error':
        console.error('Rate limit hit, retrying after delay...');
        const retryAfter = error.headers?.['retry-after'] || 60;
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        return makePayment(amount, recipient); // Retry
        
      case 'api_error':
        console.error('StateSet API error:', error.message);
        // Log to monitoring service
        break;
        
      default:
        console.error('Unknown error:', error);
    }
    
    throw error;
  }
}

​
🔄 Retry Strategy

Implement exponential backoff with jitter for transient errors: 
async function retryWithBackoff(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      // Don't retry client errors (except rate limits)
      if (error.statusCode >= 400 && error.statusCode < 500 && error.statusCode !== 429) {
        throw error;
      }
      
      if (i === maxRetries - 1) throw error;
      
      // Exponential backoff with jitter
      const delay = Math.min(1000 * Math.pow(2, i) + Math.random() * 1000, 10000);
      console.log(`Retry ${i + 1}/${maxRetries} after ${delay}ms`);
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
}

// Usage
const payment = await retryWithBackoff(() => 
  stateset.payments.create({ amount: 100, recipient: 'stateset1abc...' })
);

​
🛡️ Idempotency

Prevent duplicate operations using idempotency keys: 
const payment = await stateset.payments.create({
  amount: 100,
  recipient: 'stateset1abc...',
  idempotency_key: 'unique-operation-key-123'
});

// Safe to retry - will return the same result
const samePayment = await stateset.payments.create({
  amount: 100,
  recipient: 'stateset1abc...',
  idempotency_key: 'unique-operation-key-123'
});

​
📈 Common Error Scenarios

​
Insufficient Funds

{
  "error": {
    "type": "invalid_request_error",
    "code": "insufficient_funds",
    "message": "Account has insufficient funds for this transaction",
    "param": "amount",
    "available_balance": "50.00",
    "requested_amount": "100.00",
    "currency": "ssusd"
  }
}

​
Invalid Address

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_address",
    "message": "The recipient address is not a valid StateSet address",
    "param": "recipient",
    "provided_value": "invalid-address"
  }
}

​
Compliance Block

{
  "error": {
    "type": "compliance_error",
    "code": "transaction_blocked",
    "message": "This transaction cannot be processed due to compliance restrictions",
    "compliance_reason": "sanctions_screening",
    "request_id": "req_xyz789"
  }
}

​
🔍 Debugging Tips

​
1. Use Request IDs

Always log the request_id for support inquiries: 
try {
  const result = await stateset.someMethod();
} catch (error) {
  console.error(`Request failed: ${error.request_id}`);
  // Include request_id in bug reports
}

​
2. Enable Debug Mode

Get detailed request/response logs: 
const stateset = new StateSet({
  apiKey: process.env.STATESET_API_KEY,
  debug: true // Logs all requests/responses
});

​
3. Check Status Page

Monitor API health at status.stateset.com

​
4. Use Test Mode

Test error scenarios safely: 
// Force specific errors in test mode
const payment = await stateset.payments.create({
  amount: 100,
  recipient: 'stateset1_test_insufficient_funds', // Special test address
  currency: 'ssusd'
});

​
📊 Error Monitoring

Set up proper error tracking: 
// Example with Sentry
import * as Sentry from '@sentry/node';

async function trackError(error) {
  Sentry.captureException(error, {
    tags: {
      error_type: error.type,
      error_code: error.code,
      request_id: error.request_id
    },
    extra: {
      param: error.param,
      api_version: 'v1'
    }
  });
}

​
🆘 Getting Help

Error Reference

Complete list of all error codes

Support Portal

Contact support with request IDs

Status Page

Check current API status

Discord Community

Get help from the community