Instead of wrapping every API call in try-except blocks, you can assign a custom function to Client.handle_exception. This allows you to centrally manage errors like login requirements, challenges, and throttling.
Common exceptions to handle include:
LoginRequired: Trigger client.relogin() to refresh the session.ChallengeRequired: Attempt to resolve challenges using client.challenge_resolve(client.last_json).ClientThrottledError: Indicates an HTTP 429; you should implement backoff logic.FeedbackRequired: Indicates Instagram has blocked an action; check the feedback_message in client.last_json to determine the severity.BadPassword: Be cautious; Instagram may return this for risky IP/proxy states even if the password is correct. Avoid immediate retry loops.PleaseWaitFewMinutes: Indicates a temporary rate limit.
import logging
from instagrapi import Client
from instagrapi.exceptions import (
BadPassword,
ReloginAttemptExceeded,
ChallengeRequired,
SelectContactPointRecoveryForm,
RecaptchaChallengeForm,
FeedbackRequired,
PleaseWaitFewMinutes,
LoginRequired,
ClientThrottledError,
DirectMessageRequestsDisabled,
)
from instagrapi.utils import json_value
logger = logging.getLogger(__name__)
def handle_exception(client: Client, e: Exception):
if isinstance(e, BadPassword):
client.logger.exception(e)
if client.relogin_attempt > 0:
raise ReloginAttemptExceeded(e)
raise e
elif isinstance(e, LoginRequired):
client.logger.exception(e)
client.relogin()
return True
elif isinstance(e, ChallengeRequired):
api_path = json_value(client.last_json, "challenge", "api_path")
if api_path == "/challenge/":
logger.warning("Generic challenge flow requires manual handling or a custom resolver")
else:
try:
client.challenge_resolve(client.last_json)
except ChallengeRequired as e:
raise e
except (ChallengeRequired, SelectContactPointRecoveryForm, RecaptchaChallengeForm) as e:
raise e
return True
elif isinstance(e, FeedbackRequired):
message = client.last_json.get("feedback_message", "")
if "This action was blocked. Please try again later" in message:
logger.warning("Action blocked by Instagram: %s", message)
elif "We restrict certain activity to protect our community" in message:
logger.warning("Temporary activity restriction: %s", message)
elif "Your account has been temporarily blocked" in message:
logger.warning("Temporary account block: %s", message)
elif isinstance(e, ClientThrottledError):
logger.warning("HTTP 429 from Instagram, back off and review proxy/account pressure")
elif isinstance(e, PleaseWaitFewMinutes):
logger.warning("Please wait before retrying: %s", e)
elif isinstance(e, DirectMessageRequestsDisabled):
logger.warning("Recipient does not accept new Direct message requests: %s", e)
raise e
cl = Client()
cl.handle_exception = handle_exception
cl.login(USERNAME, PASSWORD)
