Error Handling¶

This guide explains how to handle errors and exceptions in aiorobokassa.

Exception Hierarchy¶

All exceptions inherit from RoboKassaError:

RoboKassaError (base exception)
├── SignatureError
├── APIError
├── ValidationError
├── ConfigurationError
│   └── InvalidSignatureAlgorithmError
└── XMLParseError

Common Exceptions¶

SignatureError¶

Raised when signature verification fails:

from aiorobokassa import SignatureError

try:
    client.verify_result_url(
        out_sum="100.00",
        inv_id="12345",
        signature_value="invalid_signature",
    )
except SignatureError as e:
    print(f"Signature verification failed: {e}")

APIError¶

Raised when API request fails:

from aiorobokassa import APIError

try:
    result = await client.create_invoice(
        out_sum=Decimal("100.00"),
        description="Invoice",
    )
except APIError as e:
    print(f"API error: {e.status_code}")
    print(f"Response: {e.response}")

ValidationError¶

Raised when data validation fails:

from aiorobokassa import ValidationError
from decimal import Decimal

try:
    url = client.create_payment_url(
        out_sum=Decimal("-100.00"),  # Invalid: negative amount
        description="",  # Invalid: empty description
    )
except ValidationError as e:
    print(f"Validation error: {e}")

ConfigurationError¶

Raised when client configuration is invalid:

from aiorobokassa import ConfigurationError

try:
    client = RoboKassaClient(
        merchant_login="",  # Invalid: empty login
        password1="short",  # Invalid: too short
        password2="password2",
    )
except ConfigurationError as e:
    print(f"Configuration error: {e}")

XMLParseError¶

Raised when XML response cannot be parsed:

from aiorobokassa import XMLParseError

try:
    result = await client.create_invoice(
        out_sum=Decimal("100.00"),
        description="Invoice",
    )
except XMLParseError as e:
    print(f"XML parse error: {e.response}")

Best Practices¶

Always catch specific exceptions - Don’t catch generic Exception
Log errors - Record errors for debugging
Handle gracefully - Provide user-friendly error messages
Retry logic - For transient errors, implement retry logic
Validate input - Validate data before making API calls

Example: Complete Error Handling¶

from aiorobokassa import (
    RoboKassaClient,
    SignatureError,
    APIError,
    ValidationError,
    ConfigurationError,
)
from decimal import Decimal
import logging

logger = logging.getLogger(__name__)

async def process_payment(amount: Decimal, description: str):
    try:
        client = RoboKassaClient(
            merchant_login="your_merchant_login",
            password1="password1",
            password2="password2",
        )
    except ConfigurationError as e:
        logger.error(f"Invalid configuration: {e}")
        return None

    try:
        url = client.create_payment_url(
            out_sum=amount,
            description=description,
        )
        return url
    except ValidationError as e:
        logger.error(f"Invalid payment data: {e}")
        return None
    except APIError as e:
        logger.error(f"API error: {e.status_code} - {e.response}")
        return None
    finally:
        await client.close()