Error Handling

from keystoneos.exceptions import (
    APIError,              # Base for all API errors
    AuthenticationError,   # 401
    ForbiddenError,        # 403
    NotFoundError,         # 404
    ConflictError,         # 409
    ValidationError,       # 422
    RateLimitError,        # 429
    ServerError,           # 5xx
    WebhookVerificationError,
)

try:
    settlement = await client.settlements.get("non-existent-id")
except NotFoundError:
    print("Settlement does not exist")
except ConflictError as e:
    print(f"State conflict: {e.message}")
except ValidationError as e:
    print(f"Invalid input: {e.detail}")
except RateLimitError as e:
    print(f"Rate limited. Retry after: {e.retry_after}s")
except ForbiddenError:
    print("Insufficient permissions")
except AuthenticationError:
    print("Check your M2M credentials")
except ServerError:
    print("KeyStone API issue")
except APIError as e:
    print(f"API error {e.status_code}: {e.message}")

try:
    await client.settlements.submit_compliance_decision(
        settlement_id, {"decision": "approve"}
    )
except ConflictError:
    # Settlement is no longer in COMPLIANCE_CHECKING state
    settlement = await client.settlements.get(settlement_id)
    print(f"Current state: {settlement.state}")
except ForbiddenError:
    # Missing compliance:write scope
    print("This environment doesn't have compliance permissions")

try:
    await client.settlements.list()
except RateLimitError as e:
    # All retries exhausted
    print(f"Rate limited. Retry after {e.retry_after} seconds")
    await asyncio.sleep(e.retry_after or 60)
    # Try again...

key = client.generate_idempotency_key()

# Safe to call multiple times - same key returns existing resource
settlement = await client.settlements.create({
    "idempotency_key": key,
    # ...
})