Implement Retry Mechanism with Python Management SDK

This guide is intended for developers using Contentstack Management Python who want to use the max_retries parameter and the OAuth interceptor's retry logic to retry failed requests according to configurable rules.

This mechanism improves reliability in automated and high-volume workflows by retrying failed requests caused by network issues, request timeouts, or temporary server errors.

• Python Management SDK version v1.0.0 or later
• Access to the Contentstack Management API
• One of the following authentication methods:
  • Authtoken
  • Management Token
  • OAuth-based authentication

Note: Retry behavior differs depending on how the SDK is authenticated.

• Standard authentication (Authtoken or Management Token) uses the max_retries configuration for retry behavior.
• OAuth authentication uses an interceptor-based retry mechanism with predefined retry rules and limits.

At a high level, the Python Management SDK sends a request and returns the response immediately if it succeeds. Retry logic is applied only when a request fails due to retryable conditions such as transient network issues, request timeouts, or temporary server errors.

Retry behavior differs depending on how the SDK is authenticated:

• OAuth-authenticated requests use an interceptor-based retry mechanism with predefined retry conditions and limits.
• Standard authenticated requests (Authtoken or Management Token) use the max_retries configuration to control retry behavior.

Request Execution Paths

• Successful request: If a request completes successfully, the SDK returns the response immediately and no retry logic is applied.
• Failed request (retry path): If a request fails, the SDK evaluates the error against the configured retry rules (OAuth interceptor or standard retry configuration) to determine whether the request should be retried or the error should be returned.

The following steps describe how the SDK evaluates retries once a request failure occurs.

1. Initial Request: The SDK sends the HTTP request.
2. Evaluate Response: If the response status is 200 and the request succeeds, the SDK returns the response data.
3. Check Retry Conditions: If the request fails, the SDK evaluates whether the error meets the retry conditions.
4. Decide to Retry:
   • For OAuth requests, the SDK evaluates the status code:
     • 429 (Too Many Requests)
     • 5xx server errors, except 501
     • 401 (Unauthorized), which triggers a token refresh
   • For standard requests, the SDK checks whether retries are configured.
5. Check Retry Limit: The SDK verifies whether retry attempts remain by comparing the current retry count with the configured max_retries value.
6. Calculate Retry Delay: The SDK calculates the wait time using an exponential backoff strategy.
   • For OAuth requests, the delay is calculated as:
     min(1000 × (2 raised to the power of retry_count), 30000) divided by 1000 seconds.

   • The maximum delay is capped at 30 seconds.
7. Wait Before Retry: The SDK pauses execution for the calculated delay duration.
8. Attempt Retry: The SDK retries the request and increments the retry count.
9. Exit with Final Error: If all retry attempts are exhausted, the SDK raises the final error.

Use this configuration for scripts, migrations, or CI jobs using Authtoken or Management Token, where you want to tolerate intermittent request failures.

import contentstack_management
client = contentstack_management.Client(
    authtoken='your_authtoken',
    max_retries=5,  # Number of retries before failing the request
    timeout=30  # Request timeout in seconds
)

Use OAuth authentication when your application needs token-based authorization and expects the SDK to handle token refresh and retry behavior automatically.

import contentstack_management
# OAuth requests automatically use retry logic with exponential backoff
client = contentstack_management.Client(
    oauth_config={
        'app_id': 'your_app_id',
        'client_id': 'your_client_id',
        'redirect_uri': 'your_redirect_uri',
        'client_secret': 'your_client_secret'  # Optional
    },
    max_retries=5,
    timeout=30
)

These parameters are typically adjusted based on how your application uses the Management API:

• Automation and CI pipelines: Increase timeout and use a moderate max_retries to handle intermittent connectivity and slower build environments.
• Bulk operations or migrations: Use a higher timeout for long-running requests and tune max_retries to avoid frequent manual reruns.
• Rate-limit or transient server errors: Keep max_retries conservative and rely on backoff delays to avoid repeated rapid retries.

The timeout and max_retries are commonly tuned together:

• timeout controls how long the SDK waits for a single request attempt.
• max_retries controls how many additional attempts the SDK makes after a failure.

The maximum number of retry attempts before failing the request. This parameter is passed to the API client and can be used for custom retry implementations.

Type: int

Default: 18

Example:

import contentstack_management

# Set maximum retries to 5
client = contentstack_management.Client(
    authtoken='your_authtoken',
    max_retries=5
)

Request timeout in seconds. If a request takes longer than this value, it will timeout.

Type: int or float

Default: 2

Example:

import contentstack_management

# Set timeout to 30 seconds
client = contentstack_management.Client(
    authtoken='your_authtoken',
    timeout=30,
    max_retries=5
)

This OAuth retry behavior is intentional and designed to handle common authorization and transient failure scenarios automatically. In most applications, you do not need to implement additional retry or token refresh logic when using OAuth authentication.

Note: OAuth-authenticated requests use a fixed retry limit of 3 attempts for OAuth flows. This limit is intentional and separate from the max_retries value configured on the client.

The SDK includes an automatic retry mechanism with the following characteristics:

• max_retries: 3 (hardcoded for OAuth requests)
• Retry Conditions:
  • Status code 429 (Too Many Requests)
  • Status codes 500–599 (Server errors, except 501)
  • Status code 401 (Unauthorized). Triggers token refresh before retry.
• Exponential Backoff:
  • 1st retry: 1 second (1000 ms)
  • 2nd retry: 2 seconds (2000 ms)
  • 3rd retry: 4 seconds (4000 ms)
  • Maximum delay: 30 seconds
• Delay Calculation Formula:
  min(1000 * (2 ** retry_count), 30000) / 1000 seconds

Note: The retry_count starts from 0.

Example:

import contentstack_management

# OAuth client with automatic retry
client = contentstack_management.Client(
    oauth_config={
        'app_id': 'your_app_id',
        'client_id': 'your_client_id',
        'redirect_uri': 'http://localhost:3000/callback',
        'client_secret': 'your_client_secret'
    }
)

# OAuth handler for authorization
oauth_handler = client.oauth(
    app_id='your_app_id',
    client_id='your_client_id',
    redirect_uri='http://localhost:3000/callback'
)

# Get authorization URL
auth_url = oauth_handler.authorize()

# After user authorizes and you have the code, exchange for tokens
# The SDK will automatically handle token refresh and retries
stack = client.stack('api_key')
entries = stack.content_type('content_type_uid').entry().find()

1. Token Validation:

   Before each request, the interceptor checks whether the access token is valid (not expired).

2. Automatic Token Refresh:

   If the token has expired, it automatically refreshes the token using the refresh token.

3. 401 Unauthorized Handling:

   If a request returns 401 Unauthorized:

   • The interceptor attempts to refresh the token.
   • After a successful refresh, it retries the original request with the new token.
4. Rate Limit Handling (429):

   On receiving 429 Too Many Requests, the interceptor waits using exponential backoff before retrying.

5. Server Error Handling (5xx except 501):

   On receiving retryable server errors, the interceptor retries using the same exponential backoff calculation.

6. Final Failure:

   If all retry attempts are exhausted, the SDK raises the final error.

import contentstack_management

# Default configuration (max_retries=18, timeout=2)
client = contentstack_management.Client(
    authtoken='your_authtoken'
)

This example maps to the Retry Parameters section and works with the exponential backoff behavior described in Retry Logic Flow.

Use this configuration when you want tighter control over how long the SDK waits per attempt (timeout) and how many retry attempts it makes (max_retries).

import contentstack_management

# Custom retry configuration
client = contentstack_management.Client(
    authtoken='your_authtoken',
    max_retries=5,  # Maximum 5 retry attempts
    timeout=30  # 30 second timeout
)

# Use the client to make requests
stack = client.stack('api_key')
entries = stack.content_type('content_type_uid').entry().find()

import contentstack_management

# OAuth client with automatic retry and token refresh
client = contentstack_management.Client(
    oauth_config={
        'app_id': 'your_app_id',
        'client_id': 'your_client_id',
        'redirect_uri': 'http://localhost:3000/callback',
        'client_secret': 'your_client_secret',
        'scope': ['read', 'write']
    },
    max_retries=5,
    timeout=30
)

# The OAuth interceptor automatically handles:
# - Token refresh on 401 errors
# - Retry with exponential backoff on 429 and 5xx errors
# - Maximum 3 retries for OAuth requests

import contentstack_management

# Using management token
client = contentstack_management.Client(
    management_token='your_management_token',
    max_retries=5,
    timeout=30
)

Use this configuration when you need to route requests to a specific region and still want the same retry behavior applied.

import contentstack_management
from contentstack_management.contentstack import Region

# EU region with custom retry settings
client = contentstack_management.Client(
    authtoken='your_authtoken',
    region=Region.EU.value,
    max_retries=5,
    timeout=30
)

If a request fails after all retry attempts are exhausted, consider the following checks before making changes to your code:

• Confirm the failure type: Determine whether the error is transient (network issues, rate limiting) or non-retryable (authentication or validation errors).
• Review retry configuration: Verify that max_retries and timeout values align with the reliability needs of your workload.
• Check execution environment: Network stability, DNS resolution, proxies, or CI runner limitations can affect retry outcomes.
• Inspect retry patterns: Frequent retries followed by failure may indicate persistent backend or connectivity issues rather than misconfiguration.

The following scenarios are common during transient failures and are not necessarily indicators of misconfiguration.