08 errors

Stablix uses conventional HTTP status codes and returns consistent error responses.

HTTP Status Codes

Code	Description
200	Success
201	Created
400	Bad Request — Invalid parameters
401	Unauthorized — Invalid or missing authentication
403	Forbidden — Valid auth but insufficient permissions
404	Not Found — Resource doesn't exist
409	Conflict — Resource state conflict
422	Unprocessable — Validation failed
429	Too Many Requests — Rate limit exceeded
500	Internal Server Error
503	Service Unavailable

Error Response Format

All errors follow this structure:

Error response

{
  "success": false,
  "message": "Human-readable error message",
  "error": {
    "code": "ERROR_CODE",
    "details": { }
  }
}

Example

Example error

{
  "success": false,
  "message": "Invoice not found",
  "error": {
    "code": "NOT_FOUND",
    "details": {
      "resource": "invoice",
      "id": "inv_invalid123"
    }
  }
}

Error Codes

Authentication Errors

Code	Description
INVALID_API_KEY	API key is invalid or expired
MISSING_API_KEY	No API key provided
INVALID_TOKEN	JWT token is invalid or expired
TOKEN_EXPIRED	JWT token has expired
2FA_REQUIRED	Two-factor authentication required
INVALID_2FA_CODE	Invalid 2FA code
SESSION_EXPIRED	Session has expired

Validation Errors

Code	Description
VALIDATION_ERROR	Request validation failed
INVALID_AMOUNT	Amount is invalid or out of range
INVALID_CURRENCY	Currency not supported
INVALID_CHAIN	Chain not supported
INVALID_ADDRESS	Wallet address is invalid
INVALID_EMAIL	Email format is invalid

Resource Errors

Code	Description
NOT_FOUND	Resource not found
ALREADY_EXISTS	Resource already exists
CONFLICT	Resource state conflict

Business Logic Errors

Code	Description
INVOICE_EXPIRED	Invoice has expired
INVOICE_ALREADY_PAID	Invoice is already paid
INVOICE_NOT_PAID	Invoice is not in paid status
INSUFFICIENT_BALANCE	Wallet has insufficient balance
VOLUME_LIMIT_EXCEEDED	Monthly volume limit exceeded
TRANSACTION_LIMIT_EXCEEDED	Single transaction limit exceeded
KYC_REQUIRED	KYC verification required
WALLET_LIMIT_EXCEEDED	Maximum wallets reached for tier
DISPUTE_EXISTS	Dispute already exists for invoice
BUFFER_EXPIRED	Escrow buffer period has ended

Rate Limiting

Code	Description
RATE_LIMIT_EXCEEDED	Too many requests

Validation Error Details

Validation errors include field-level details:

Validation error example

{
  "success": false,
  "message": "Validation failed",
  "error": {
    "code": "VALIDATION_ERROR",
    "details": {
      "fields": [
        {
          "field": "amount",
          "message": "Amount must be greater than 0"
        },
        {
          "field": "chain",
          "message": "Chain must be 'solana' or 'base'"
        }
      ]
    }
  }
}

Rate Limiting

API requests are rate limited per API key:

Endpoint Type	Limit
General API	100 requests/15 min
Authentication	10 requests/15 min
Webhooks	1000 requests/15 min

Rate Limit Headers

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1705320000

Rate Limit Response

Rate limit response

{
  "success": false,
  "message": "Too many requests, please try again later",
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "details": {
      "retry_after": 300
    }
  }
}

Handling Errors

JavaScript Example

createInvoice (JavaScript)

async function createInvoice(data) {
  try {
    const response = await fetch('https://api.stablix.xyz/api/v1/invoices', {
      method: 'POST',
      headers: {
        'X-API-Key': process.env.STABLIX_API_KEY,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(data)
    });

    const result = await response.json();

    if (!result.success) {
      switch (result.error.code) {
        case 'VALIDATION_ERROR':
          // Handle validation errors
          console.error('Validation failed:', result.error.details.fields);
          break;
        case 'VOLUME_LIMIT_EXCEEDED':
          // Prompt user to upgrade KYC
          console.error('Volume limit exceeded');
          break;
        case 'RATE_LIMIT_EXCEEDED':
          // Retry after delay
          const retryAfter = result.error.details.retry_after;
          await sleep(retryAfter * 1000);
          return createInvoice(data);
        default:
          console.error('Error:', result.message);
      }
      return null;
    }

    return result.data;
  } catch (error) {
    console.error('Network error:', error);
    return null;
  }
}

Python Example

create_invoice (Python)

import requests
import time

def create_invoice(data):
    try:
        response = requests.post(
            'https://api.stablix.xyz/api/v1/invoices',
            headers={
                'X-API-Key': os.environ['STABLIX_API_KEY'],
                'Content-Type': 'application/json'
            },
            json=data
        )
        
        result = response.json()
        
        if not result['success']:
            error_code = result['error']['code']
            
            if error_code == 'VALIDATION_ERROR':
                print('Validation failed:', result['error']['details']['fields'])
            elif error_code == 'RATE_LIMIT_EXCEEDED':
                retry_after = result['error']['details']['retry_after']
                time.sleep(retry_after)
                return create_invoice(data)
            else:
                print('Error:', result['message'])
            
            return None
        
        return result['data']
    
    except requests.exceptions.RequestException as e:
        print('Network error:', e)
        return None

Best Practices

• Always check success field — Don't assume requests succeed.

• Handle specific error codes — Different errors need different handling.

• Implement retry logic — For rate limits and transient errors.

• Log errors — Keep records for debugging.

• Show user-friendly messages — Don't expose raw error messages to end users.

• Validate before sending — Catch obvious validation errors client-side.

Getting Help

If you encounter unexpected errors:

• Check the error code and message

• Review the API reference for endpoint requirements

• Search our FAQ for common issues

• Contact [email protected] with:

  • Error code and message

  • Request details (endpoint, parameters)

  • Timestamp

  • Your merchant ID