{
  "schema_version": 2,
  "id": "develop/clients/redis-py/error-handling",
  "title": "Error handling",
  "url": "https://redis.io/docs/latest/develop/clients/redis-py/error-handling/",
  "summary": "Learn how to handle errors when using redis-py",
  "tags": [],
  "last_updated": "2026-08-27T15:55:18+01:00",
  "page_type": "content",
  "content_hash": "eee2b6552e05dd60c198cad0131a225dba147c42c7b247fe7760a9f8c165ea98",
  "sections": [
    {
      "id": "overview",
      "title": "Overview",
      "role": "overview",
      "text": "redis-py uses **exceptions** to signal errors. The redis-py documentation mainly\nshows the \"happy path\" in code examples and omits error handling for brevity.\nThis page explains how\nredis-py's error handling works and how to apply common error handling patterns.\nFor an overview of error types and handling strategies, see\n[Error handling](https://redis.io/docs/latest/develop/clients/error-handling).\nSee also [Production usage](https://redis.io/docs/latest/develop/clients/redis-py/produsage)\nfor more information on connection management, timeouts, and other aspects of\napp reliability."
    },
    {
      "id": "exception-hierarchy",
      "title": "Exception hierarchy",
      "role": "errors",
      "text": "redis-py organizes exceptions in a hierarchy. The base exception is `redis.RedisError`, with specific subclasses for different error types, as shown below:\n\n[code example]"
    },
    {
      "id": "key-exceptions",
      "title": "Key exceptions",
      "role": "content",
      "text": "The following exceptions are the most commonly encountered in redis-py applications.\nSee\n[Categories of errors](https://redis.io/docs/latest/develop/clients/error-handling#categories-of-errors)\nfor a more detailed discussion of these errors and their causes.\n\n| Exception | When it occurs | Recoverable | Recommended action |\n|---|---|---|---|\n| `redis.ConnectionError` | Network or connection issues | ✅ | Retry with backoff or fall back to alternative |\n| `redis.TimeoutError` | Operation exceeded timeout | ✅ | Retry with backoff |\n| `redis.ResponseError` | Invalid command or Redis error response | ❌ | Fix the command or arguments |\n| `redis.DataError` | Data serialization/deserialization issues | ⚠️ | Log, invalidate cache, fetch fresh data |"
    },
    {
      "id": "applying-error-handling-patterns",
      "title": "Applying error handling patterns",
      "role": "content",
      "text": "The [Error handling](https://redis.io/docs/latest/develop/clients/error-handling) overview\ndescribes four main patterns. The sections below show how to implement them in\nredis-py:"
    },
    {
      "id": "pattern-1-fail-fast",
      "title": "Pattern 1: Fail fast",
      "role": "content",
      "text": "Catch specific exceptions that represent unrecoverable errors and re-raise them (see\n[Pattern 1: Fail fast](https://redis.io/docs/latest/develop/clients/error-handling#pattern-1-fail-fast)\nfor a full description):\n\n[code example]"
    },
    {
      "id": "pattern-2-graceful-degradation",
      "title": "Pattern 2: Graceful degradation",
      "role": "content",
      "text": "Catch connection errors and fall back to an alternative (see\n[Pattern 2: Graceful degradation](https://redis.io/docs/latest/develop/clients/error-handling#pattern-2-graceful-degradation)\nfor a full description):\n\n[code example]"
    },
    {
      "id": "pattern-3-retry-with-backoff",
      "title": "Pattern 3: Retry with backoff",
      "role": "content",
      "text": "Retry on temporary errors like timeouts (see\n[Pattern 3: Retry with backoff](https://redis.io/docs/latest/develop/clients/error-handling#pattern-3-retry-with-backoff)\nfor a full description). redis-py has built-in retry logic\nwhich is highly configurable. You can customize the retry strategy\n(or supply your own custom strategy) and you can also specify which errors\nshould be retried. See\n[Production usage](https://redis.io/docs/latest/develop/clients/redis-py/produsage#retries)\nfor more information."
    },
    {
      "id": "pattern-4-log-and-continue",
      "title": "Pattern 4: Log and continue",
      "role": "content",
      "text": "Log non-critical errors and continue (see\n[Pattern 4: Log and continue](https://redis.io/docs/latest/develop/clients/error-handling#pattern-4-log-and-continue)\nfor a full description):\n\n[code example]"
    },
    {
      "id": "async-error-handling",
      "title": "Async error handling",
      "role": "content",
      "text": "Error handling works the usual way when you use `async`/`await`,\nas shown in the example below:\n\n[code example]"
    },
    {
      "id": "see-also",
      "title": "See also",
      "role": "related",
      "text": "- [Error handling](https://redis.io/docs/latest/develop/clients/error-handling)\n- [Production usage](https://redis.io/docs/latest/develop/clients/redis-py/produsage)"
    }
  ],
  "examples": [
    {
      "id": "exception-hierarchy-ex0",
      "language": "hierarchy {type=\"exception\"}",
      "code": "\"RedisError\":\n    _meta:\n        description: \"Base class for all redis-py exceptions\"\n    \"ConnectionError\":\n        \"TimeoutError\":\n        \"BusyLoadingError\":\n    \"ResponseError\":\n    \"InvalidResponse\":\n    \"DataError\":\n    \"PubSubError\":\n    \"...\":\n        _meta:\n            ellipsis: true\n            description: \"Other exception types\"",
      "section_id": "exception-hierarchy"
    },
    {
      "id": "pattern-1-fail-fast-ex0",
      "language": "python",
      "code": "import redis\n\nr = redis.Redis()\n\ntry:\n    result = r.get(key)\nexcept redis.ResponseError:\n    # This indicates a bug in the code\n    raise",
      "section_id": "pattern-1-fail-fast"
    },
    {
      "id": "pattern-2-graceful-degradation-ex0",
      "language": "python",
      "code": "try:\n    cached_value = r.get(key)\n    if cached_value:\n        return cached_value\nexcept redis.ConnectionError:\n    logger.warning(\"Cache unavailable, using database\")\n\n# Fallback to database\nreturn database.get(key)",
      "section_id": "pattern-2-graceful-degradation"
    },
    {
      "id": "pattern-4-log-and-continue-ex0",
      "language": "python",
      "code": "try:\n    r.setex(key, 3600, value)\nexcept redis.ConnectionError:\n    logger.warning(f\"Failed to cache {key}, continuing without cache\")\n    # Application continues normally",
      "section_id": "pattern-4-log-and-continue"
    },
    {
      "id": "async-error-handling-ex0",
      "language": "python",
      "code": "import redis.asyncio as redis\n\nasync def get_with_fallback(key):\n    r = await redis.from_url(\"redis://localhost\")\n    try:\n        return await r.get(key)\n    except redis.ConnectionError:\n        logger.warning(\"Cache unavailable\")\n        return await database.get(key)\n    finally:\n        await r.close()",
      "section_id": "async-error-handling"
    }
  ]
}