Error Handling

The Renesis Stellar DEX Vaults API uses conventional HTTP response codes to indicate the success or failure of API requests. All error responses follow a consistent structure to provide clear information about what went wrong and how to fix it.

Error Response Format

All API errors return a standardized JSON response structure:

{
  "success": false,
  "message": "Human-readable error description",
  "errors": [
    {
      "field": "fieldName",
      "message": "Specific error message for this field",
      "value": "invalid_value_provided"
    }
  ]
}

Response Fields

success (boolean): Always false for error responses
message (string): General error description explaining what went wrong
errors (array, optional): Detailed field-specific validation errors
- field (string): Name of the field that caused the error
- message (string): Specific error message for this field
- value (any, optional): The invalid value that was provided

HTTP Status Codes

The API uses standard HTTP status codes to indicate different types of errors:

200 OK

Request succeeded. The response body contains the requested data.

{
  "success": true,
  "message": "Operation completed successfully",
  "data": {
    // Response data
  }
}

201 Created

Resource was successfully created. The response body contains the new resource data.

{
  "success": true,
  "message": "Vault created successfully",
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "vaultName": "New Trading Vault",
    // ... other vault fields
  }
}

400 Bad Request

The request was invalid due to malformed syntax, invalid parameters, or validation errors.

Common Causes:

Invalid request body format
Missing required fields
Invalid field values
Malformed JSON
Invalid query parameters

Example Response:

{
  "success": false,
  "message": "Validation failed",
  "errors": [
    {
      "field": "vaultName",
      "message": "Vault name must be between 2 and 100 characters",
      "value": ""
    },
    {
      "field": "vaultOwner",
      "message": "Invalid Stellar address format",
      "value": "invalid-address"
    },
    {
      "field": "maxTradeSize",
      "message": "Maximum trade size must be between 0 and 100",
      "value": 150
    }
  ]
}

Validation Error Examples:

Invalid Vault Name

{
  "success": false,
  "message": "Validation failed",
  "errors": [
    {
      "field": "vaultName",
      "message": "Vault name must be between 2 and 100 characters",
      "value": "A"
    }
  ]
}

Invalid Stellar Address

{
  "success": false,
  "message": "Validation failed",
  "errors": [
    {
      "field": "vaultOwner",
      "message": "Invalid Stellar address format. Must start with 'G' and be 56 characters long",
      "value": "INVALID_ADDRESS"
    }
  ]
}

Invalid MongoDB ObjectId

{
  "success": false,
  "message": "Invalid vault ID format",
  "errors": [
    {
      "field": "id",
      "message": "Must be a valid MongoDB ObjectId (24 character hex string)",
      "value": "invalid-id"
    }
  ]
}

Invalid Pagination Parameters

{
  "success": false,
  "message": "Invalid query parameters",
  "errors": [
    {
      "field": "limit",
      "message": "Limit must be between 1 and 100",
      "value": 150
    },
    {
      "field": "page",
      "message": "Page must be a positive integer",
      "value": 0
    }
  ]
}

Invalid Trade Settings

{
  "success": false,
  "message": "Validation failed",
  "errors": [
    {
      "field": "maxTradeSize",
      "message": "Max trade size is required when enabling trading",
      "value": null
    },
    {
      "field": "dailyTradeLimit",
      "message": "Daily trade limit must be a positive integer",
      "value": -5
    },
    {
      "field": "slippageTolerance",
      "message": "Slippage tolerance must be between 0 and 100",
      "value": 150
    }
  ]
}

401 Unauthorized

Authentication failed. The request lacks valid authentication credentials.

Common Causes:

Missing Authorization header
Invalid API key
Expired API key
Malformed Authorization header

Example Response:

{
  "success": false,
  "message": "Authentication required. Please provide a valid API key in the Authorization header."
}

Authentication Error Examples:

Missing API Key

{
  "success": false,
  "message": "Missing Authorization header. Please include 'Authorization: Bearer YOUR_API_KEY' in your request."
}

Invalid API Key Format

{
  "success": false,
  "message": "Invalid Authorization header format. Use 'Bearer YOUR_API_KEY'."
}

Invalid API Key

{
  "success": false,
  "message": "Invalid API key. Please check your API key and try again."
}

Expired API Key

{
  "success": false,
  "message": "API key has expired. Please generate a new API key from your dashboard."
}

404 Not Found

The requested resource could not be found.

Common Causes:

Invalid vault ID
Vault doesn’t exist
Invalid endpoint URL
Resource was deleted

Example Response:

{
  "success": false,
  "message": "Vault not found"
}

Not Found Error Examples:

Vault Not Found by ID

{
  "success": false,
  "message": "Vault not found with ID: 507f1f77bcf86cd799439011"
}

Vault Not Found by Address

{
  "success": false,
  "message": "Vault not found with address: CA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ"
}

No Vaults Found for Owner

{
  "success": false,
  "message": "No vaults found for owner: GA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ"
}

Invalid Endpoint

{
  "success": false,
  "message": "Endpoint not found. Please check the API documentation for valid endpoints."
}

409 Conflict

The request conflicts with the current state of the resource.

Common Causes:

Duplicate vault address
Resource already exists
Conflicting state changes

Example Response:

{
  "success": false,
  "message": "Vault with this address already exists",
  "errors": [
    {
      "field": "vaultAddress",
      "message": "Vault address must be unique",
      "value": "CA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ"
    }
  ]
}

Conflict Error Examples:

Duplicate Vault Address

{
  "success": false,
  "message": "Vault with this address already exists",
  "errors": [
    {
      "field": "vaultAddress",
      "message": "A vault with address 'CA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ' already exists",
      "value": "CA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ"
    }
  ]
}

Duplicate Vault Name for Owner

{
  "success": false,
  "message": "Vault name already exists for this owner",
  "errors": [
    {
      "field": "vaultName",
      "message": "You already have a vault named 'My Trading Vault'",
      "value": "My Trading Vault"
    }
  ]
}

429 Too Many Requests

Rate limit exceeded. The client has sent too many requests in a given time period.

Rate Limiting Details:

Window: 15 minutes (900,000 ms)
Limit: 100 requests per window per API key
Reset: Automatic after window expires

Example Response:

{
  "success": false,
  "message": "Rate limit exceeded. Please wait before making more requests.",
  "retryAfter": 300
}

Rate Limit Headers:

All responses include rate limiting information in headers:

X-RateLimit-Limit: Maximum requests allowed per window
X-RateLimit-Remaining: Remaining requests in current window
X-RateLimit-Reset: Timestamp when the rate limit window resets
Retry-After: Seconds to wait before retrying (only on 429 responses)

Rate Limit Error Examples:

Standard Rate Limit Exceeded

{
  "success": false,
  "message": "Rate limit exceeded. You have made 100 requests in the last 15 minutes. Please wait 5 minutes before making more requests.",
  "retryAfter": 300
}

Burst Protection Triggered

{
  "success": false,
  "message": "Too many requests in quick succession. Please wait 30 seconds before retrying.",
  "retryAfter": 30
}

500 Internal Server Error

An unexpected error occurred on the server.

Common Causes:

Database connection issues
Stellar network connectivity problems
Unexpected server errors
Third-party service failures

Example Response:

{
  "success": false,
  "message": "An internal server error occurred. Please try again later or contact support if the problem persists."
}

Internal Error Examples:

Database Connection Error

{
  "success": false,
  "message": "Database connection error. Please try again in a few moments."
}

Stellar Network Error

{
  "success": false,
  "message": "Unable to connect to Stellar network. Please try again later."
}

Unexpected Server Error

{
  "success": false,
  "message": "An unexpected error occurred. Our team has been notified. Please try again later."
}

Common Error Scenarios

Validation Errors

Invalid Field Types

curl -X POST "https://api.renesis.fi/api/vaults" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "vaultName": 123,
    "tradePermission": "yes",
    "maxTradeSize": "invalid"
  }'

Response:

{
  "success": false,
  "message": "Validation failed",
  "errors": [
    {
      "field": "vaultName",
      "message": "Vault name must be a string",
      "value": 123
    },
    {
      "field": "tradePermission",
      "message": "Trade permission must be a boolean (true or false)",
      "value": "yes"
    },
    {
      "field": "maxTradeSize",
      "message": "Max trade size must be a number",
      "value": "invalid"
    }
  ]
}

Missing Required Fields

curl -X POST "https://api.renesis.fi/api/vaults" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "vaultName": "Incomplete Vault"
  }'

Response:

{
  "success": false,
  "message": "Validation failed",
  "errors": [
    {
      "field": "vaultOwner",
      "message": "Vault owner is required",
      "value": null
    },
    {
      "field": "vaultAddress",
      "message": "Vault address is required",
      "value": null
    }
  ]
}

Field Length Violations

curl -X POST "https://api.renesis.fi/api/vaults" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "vaultName": "A",
    "vaultOwner": "GA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",
    "vaultAddress": "CA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ"
  }'

Response:

{
  "success": false,
  "message": "Validation failed",
  "errors": [
    {
      "field": "vaultName",
      "message": "Vault name must be between 2 and 100 characters",
      "value": "A"
    }
  ]
}

Authentication Errors

Missing Authorization Header

curl -X GET "https://api.renesis.fi/api/vaults"

Response:

{
  "success": false,
  "message": "Missing Authorization header. Please include 'Authorization: Bearer YOUR_API_KEY' in your request."
}

Malformed Authorization Header

curl -X GET "https://api.renesis.fi/api/vaults" \
  -H "Authorization: YOUR_API_KEY"

Response:

{
  "success": false,
  "message": "Invalid Authorization header format. Use 'Bearer YOUR_API_KEY'."
}

Resource Not Found Errors

Invalid Vault ID

curl -X GET "https://api.renesis.fi/api/vaults/invalid-id" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "success": false,
  "message": "Invalid vault ID format",
  "errors": [
    {
      "field": "id",
      "message": "Must be a valid MongoDB ObjectId (24 character hex string)",
      "value": "invalid-id"
    }
  ]
}

Vault Not Found

curl -X GET "https://api.renesis.fi/api/vaults/507f1f77bcf86cd799439999" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "success": false,
  "message": "Vault not found with ID: 507f1f77bcf86cd799439999"
}

Rate Limiting Errors

Rate Limit Exceeded

When you exceed 100 requests in 15 minutes: Response:

{
  "success": false,
  "message": "Rate limit exceeded. You have made 100 requests in the last 15 minutes. Please wait 8 minutes before making more requests.",
  "retryAfter": 480
}

Response Headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1642694400
Retry-After: 480

Troubleshooting Guide

Common Issues and Solutions

1. Authentication Problems

Issue: Getting 401 Unauthorized errors Solutions:

Verify your API key is correct
Ensure you’re using the Bearer prefix: Authorization: Bearer YOUR_API_KEY
Check that your API key hasn’t expired
Regenerate your API key if necessary

Test Authentication:

curl -X GET "https://api.renesis.fi/api/health" \
  -H "Authorization: Bearer YOUR_API_KEY"

2. Validation Errors

Issue: Getting 400 Bad Request with validation errors Solutions:

Check all required fields are provided
Verify field types match the expected format
Ensure Stellar addresses are valid (56 characters, correct prefix)
Validate numeric ranges (e.g., maxTradeSize: 0-100)

Common Validation Rules:

Vault Name: 2-100 characters, string
Vault Owner: Stellar address starting with ‘G’, 56 characters
Vault Address: Stellar contract address starting with ‘C’, 56 characters
Max Trade Size: Number between 0-100
Daily Trade Limit: Positive integer
Slippage Tolerance: Number between 0-100

3. Rate Limiting Issues

Issue: Getting 429 Too Many Requests Solutions:

Implement exponential backoff in your retry logic
Respect the Retry-After header value
Monitor rate limit headers to avoid hitting limits
Consider caching responses to reduce API calls

Rate Limit Best Practices:

// Example retry logic with exponential backoff
async function apiRequest(url, options, retries = 3) {
  try {
    const response = await fetch(url, options);
    
    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After');
      const delay = retryAfter ? parseInt(retryAfter) * 1000 : Math.pow(2, 4 - retries) * 1000;
      
      if (retries > 0) {
        await new Promise(resolve => setTimeout(resolve, delay));
        return apiRequest(url, options, retries - 1);
      }
    }
    
    return response;
  } catch (error) {
    if (retries > 0) {
      await new Promise(resolve => setTimeout(resolve, 1000));
      return apiRequest(url, options, retries - 1);
    }
    throw error;
  }
}

4. Resource Not Found

Issue: Getting 404 Not Found errors Solutions:

Verify the resource ID is correct
Check that the resource hasn’t been deleted
Ensure you’re using the correct endpoint URL
Confirm you have access to the requested resource

5. Duplicate Resource Conflicts

Issue: Getting 409 Conflict errors Solutions:

Check if a vault with the same address already exists
Use unique vault addresses for each vault
Consider updating existing resources instead of creating new ones

6. Server Errors

Issue: Getting 500 Internal Server Error Solutions:

Wait a few moments and retry the request
Check the API status page for known issues
Contact support if the problem persists
Implement retry logic with exponential backoff

Error Handling Best Practices

1. Implement Proper Error Handling

async function createVault(vaultData) {
  try {
    const response = await fetch('/api/vaults', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${apiKey}`
      },
      body: JSON.stringify(vaultData)
    });

    const result = await response.json();

    if (!response.ok) {
      // Handle different error types
      switch (response.status) {
        case 400:
          console.error('Validation errors:', result.errors);
          break;
        case 401:
          console.error('Authentication failed:', result.message);
          break;
        case 409:
          console.error('Vault already exists:', result.message);
          break;
        case 429:
          console.error('Rate limit exceeded:', result.message);
          break;
        case 500:
          console.error('Server error:', result.message);
          break;
        default:
          console.error('Unexpected error:', result.message);
      }
      throw new Error(result.message);
    }

    return result.data;
  } catch (error) {
    console.error('API request failed:', error);
    throw error;
  }
}

2. Validate Data Before Sending

function validateVaultData(vaultData) {
  const errors = [];

  if (!vaultData.vaultName || vaultData.vaultName.length < 2 || vaultData.vaultName.length > 100) {
    errors.push('Vault name must be between 2 and 100 characters');
  }

  if (!vaultData.vaultOwner || !vaultData.vaultOwner.startsWith('G') || vaultData.vaultOwner.length !== 56) {
    errors.push('Invalid vault owner address format');
  }

  if (!vaultData.vaultAddress || !vaultData.vaultAddress.startsWith('C') || vaultData.vaultAddress.length !== 56) {
    errors.push('Invalid vault address format');
  }

  if (vaultData.maxTradeSize !== undefined && (vaultData.maxTradeSize < 0 || vaultData.maxTradeSize > 100)) {
    errors.push('Max trade size must be between 0 and 100');
  }

  return errors;
}

3. Monitor Rate Limits

function checkRateLimit(response) {
  const remaining = response.headers.get('X-RateLimit-Remaining');
  const reset = response.headers.get('X-RateLimit-Reset');
  
  if (remaining && parseInt(remaining) < 10) {
    console.warn(`Rate limit warning: ${remaining} requests remaining`);
    console.warn(`Rate limit resets at: ${new Date(parseInt(reset) * 1000)}`);
  }
}

4. Implement Retry Logic

async function apiRequestWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch(url, options);
      
      if (response.status === 429) {
        const retryAfter = response.headers.get('Retry-After');
        const delay = retryAfter ? parseInt(retryAfter) * 1000 : Math.pow(2, attempt) * 1000;
        
        if (attempt < maxRetries) {
          console.log(`Rate limited. Retrying in ${delay}ms...`);
          await new Promise(resolve => setTimeout(resolve, delay));
          continue;
        }
      }
      
      if (response.status >= 500 && attempt < maxRetries) {
        const delay = Math.pow(2, attempt) * 1000;
        console.log(`Server error. Retrying in ${delay}ms...`);
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }
      
      return response;
    } catch (error) {
      if (attempt === maxRetries) {
        throw error;
      }
      
      const delay = Math.pow(2, attempt) * 1000;
      console.log(`Request failed. Retrying in ${delay}ms...`);
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
}

Error Response Examples by Endpoint

Vault Creation Errors

POST /api/vaults

// Missing required fields
{
  "success": false,
  "message": "Validation failed",
  "errors": [
    {
      "field": "vaultOwner",
      "message": "Vault owner is required",
      "value": null
    },
    {
      "field": "vaultAddress",
      "message": "Vault address is required",
      "value": null
    }
  ]
}

// Invalid Stellar addresses
{
  "success": false,
  "message": "Validation failed",
  "errors": [
    {
      "field": "vaultOwner",
      "message": "Invalid Stellar address format. Must start with 'G' and be 56 characters long",
      "value": "INVALID_OWNER_ADDRESS"
    },
    {
      "field": "vaultAddress",
      "message": "Invalid Stellar contract address format. Must start with 'C' and be 56 characters long",
      "value": "INVALID_VAULT_ADDRESS"
    }
  ]
}

// Duplicate vault address
{
  "success": false,
  "message": "Vault with this address already exists",
  "errors": [
    {
      "field": "vaultAddress",
      "message": "A vault with address 'CA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ' already exists",
      "value": "CA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ"
    }
  ]
}

Vault Retrieval Errors

GET /api/vaults/:id

// Invalid ObjectId format
{
  "success": false,
  "message": "Invalid vault ID format",
  "errors": [
    {
      "field": "id",
      "message": "Must be a valid MongoDB ObjectId (24 character hex string)",
      "value": "invalid-id"
    }
  ]
}

// Vault not found
{
  "success": false,
  "message": "Vault not found with ID: 507f1f77bcf86cd799439999"
}

Vault Update Errors

PUT /api/vaults/:id

// Invalid trade settings
{
  "success": false,
  "message": "Validation failed",
  "errors": [
    {
      "field": "maxTradeSize",
      "message": "Max trade size is required when enabling trading",
      "value": null
    },
    {
      "field": "dailyTradeLimit",
      "message": "Daily trade limit must be a positive integer",
      "value": -5
    }
  ]
}

// Vault not found
{
  "success": false,
  "message": "Vault not found with ID: 507f1f77bcf86cd799439999"
}

Search and Filtering Errors

GET /api/vaults

// Invalid query parameters
{
  "success": false,
  "message": "Invalid query parameters",
  "errors": [
    {
      "field": "limit",
      "message": "Limit must be between 1 and 100",
      "value": 150
    },
    {
      "field": "page",
      "message": "Page must be a positive integer",
      "value": 0
    },
    {
      "field": "sortBy",
      "message": "Sort field must be one of: creationDate, creationLedger, vaultName, updatedAt",
      "value": "invalidField"
    }
  ]
}

Support and Contact

If you encounter persistent errors or need additional help:

Check API Status: Visit our status page for known issues
Review Documentation: Ensure you’re following the correct API patterns
Contact Support: Reach out to our support team with:
- Error response details
- Request details (without sensitive data)
- Timestamp of the error
- Your API key ID (not the full key)

Support Channels

Email: support@renesis.fi
Documentation: API Documentation
Status Page: status.renesis.fi

Remember to never share your full API key in support requests. Only provide the key ID or first few characters if needed for identification.

Getting Started

Vaults

Smart Contracts

Order Execution

Swap Infrastructure

Contract Addresses

API Reference

Disclaimers

​Error Handling

​Error Response Format

​Response Fields

​HTTP Status Codes

​200 OK

​201 Created

​400 Bad Request

​Common Causes:

​Example Response:

​Validation Error Examples:

​401 Unauthorized

​Common Causes:

​Example Response:

​Authentication Error Examples:

​404 Not Found

​Common Causes:

​Example Response:

​Not Found Error Examples:

​409 Conflict

​Common Causes:

​Example Response:

​Conflict Error Examples:

​429 Too Many Requests

​Rate Limiting Details:

​Example Response:

​Rate Limit Headers:

​Rate Limit Error Examples:

​500 Internal Server Error

​Common Causes:

​Example Response:

​Internal Error Examples:

​Common Error Scenarios

​Validation Errors

​Invalid Field Types

​Missing Required Fields

​Field Length Violations

​Authentication Errors

​Missing Authorization Header

​Malformed Authorization Header

​Resource Not Found Errors

​Invalid Vault ID

​Vault Not Found

​Rate Limiting Errors

​Rate Limit Exceeded

​Troubleshooting Guide

​Common Issues and Solutions

​1. Authentication Problems

​2. Validation Errors

​3. Rate Limiting Issues

​4. Resource Not Found

​5. Duplicate Resource Conflicts

​6. Server Errors

​Error Handling Best Practices

​1. Implement Proper Error Handling

​2. Validate Data Before Sending

​3. Monitor Rate Limits

​4. Implement Retry Logic

​Error Response Examples by Endpoint

​Vault Creation Errors

​Vault Retrieval Errors

​Vault Update Errors

​Search and Filtering Errors

​Support and Contact

​Support Channels

Error Handling

Error Response Format

Response Fields

HTTP Status Codes

200 OK

201 Created

400 Bad Request

Common Causes:

Example Response:

Validation Error Examples:

401 Unauthorized

Common Causes:

Example Response:

Authentication Error Examples:

404 Not Found

Common Causes:

Example Response:

Not Found Error Examples:

409 Conflict

Common Causes:

Example Response:

Conflict Error Examples:

429 Too Many Requests

Rate Limiting Details:

Example Response:

Rate Limit Headers:

Rate Limit Error Examples:

500 Internal Server Error

Common Causes:

Example Response:

Internal Error Examples:

Common Error Scenarios

Validation Errors

Invalid Field Types

Missing Required Fields

Field Length Violations

Authentication Errors

Missing Authorization Header

Malformed Authorization Header

Resource Not Found Errors

Invalid Vault ID

Vault Not Found

Rate Limiting Errors

Rate Limit Exceeded

Troubleshooting Guide

Common Issues and Solutions

1. Authentication Problems

2. Validation Errors

3. Rate Limiting Issues

4. Resource Not Found

5. Duplicate Resource Conflicts

6. Server Errors

Error Handling Best Practices

1. Implement Proper Error Handling

2. Validate Data Before Sending

3. Monitor Rate Limits

4. Implement Retry Logic

Error Response Examples by Endpoint

Vault Creation Errors

Vault Retrieval Errors

Vault Update Errors

Search and Filtering Errors

Support and Contact

Support Channels