Handle InstagramException errors in JxInsta

Use InstagramException.getReason() to respond to specific Instagram API failures — auth errors, rate limits, private accounts, and network issues — in JxInsta.

InstagramException extends Exception, which means it is a checked exception — the compiler requires you to either catch it or declare it in your method signature. Every method in JxInsta that communicates with Instagram can throw it. The exception carries a Reasons enum value accessible via getReason(), which identifies the specific cause of the failure. Branching on that value lets you respond precisely rather than treating every error the same way.

Handling errors by reason

The example below shows a switch expression covering the most common failure cases. Use a default branch to catch any reason not explicitly listed, including UNKNOWN and future values added to the enum.

Handling InstagramException with a switch on getReason()

try {
    Profile profile = insta.getProfile("someuser");
    profile.follow();
} catch (InstagramException e) {
    switch (e.getReason()) {
        case INCORRECT_PASSWORD -> System.out.println("Wrong password");
        case LOGIN_EXPIRED -> System.out.println("Session expired, re-login needed");
        case RATE_LIMITED, THROTTLED -> System.out.println("Rate limited, slow down");
        case CHECKPOINT_REQUIRED -> System.out.println("Instagram challenge required");
        case PRIVATE_ACCOUNT -> System.out.println("Account is private");
        case USER_NOT_FOUND -> System.out.println("User not found");
        default -> System.out.println("Error: " + e.getMessage());
    }
}

Reasons reference

The Reasons enum covers four broad categories. Expand each section below for the full list of values and guidance on how to respond to them.

Authentication errors

These reasons indicate a problem with the session or login credentials. They require user interaction or re-authentication and should not be silently retried.

Reason	Description
INCORRECT_PASSWORD	The supplied password does not match the account. Prompt the user to re-enter credentials.
LOGIN_EXPIRED	The session cookie has expired. Clear the stored session and log in again.
TWO_FACTOR_REQUIRED	The account has two-factor authentication enabled. Collect the one-time code from the user and pass it to the two-factor login method.
CHECKPOINT_REQUIRED	Instagram has flagged the session and requires the user to complete a challenge (email or SMS verification). This cannot be resolved programmatically.

Rate limiting and blocking

These reasons indicate that Instagram has restricted the account or IP address due to request volume or suspicious activity. Back off and wait before retrying.

Reason	Description
RATE_LIMITED	Too many requests in a short period. Stop all requests for at least 15 minutes.
THROTTLED	Request cadence is too high. Pause for at least 5 minutes before continuing.
SENTRY_BLOCK	The session has been blocked by Instagram’s automated systems. The account may need manual review.
FORBIDDEN	The action is not permitted for this account or target. Check account permissions.
PROXY_ADDRESS_BLOCKED	The IP address of the proxy or server is blocked by Instagram. Use a different egress address.

Content and target errors

These reasons indicate that the requested resource cannot be accessed or does not exist. They are typically non-retryable and should be handled by adjusting the request.

Reason	Description
PRIVATE_ACCOUNT	The target account is private and the authenticated user does not follow them.
USER_NOT_FOUND	No account exists with the given username or user ID.
MEDIA_UNAVAILABLE	The post or story has been deleted or is otherwise inaccessible.
INVALID_MEDIA_ID	The media ID is malformed or does not correspond to a real post.
INVALID_TARGET_USER	The user ID supplied to the action is not valid for the operation.

Network and protocol errors

These reasons indicate a failure at the transport or protocol layer rather than an Instagram-level rejection. They may be transient and worth retrying after a short delay.

Reason	Description
IO	A low-level I/O failure occurred during the request. Check connectivity and retry.
REQUEST_TIMEOUT	The request did not receive a response within the allowed time. Retry with backoff.
NOT_FOUND	The API endpoint returned a 404. This may indicate a changed API path or an invalid resource.
BAD_REQUEST	The request was malformed. Check the parameters passed to the method.
PARSING_FAILED	JxInsta received a response from Instagram but could not parse it. The API response format may have changed.

Other

Miscellaneous reasons that do not fit cleanly into the above categories.

Reason	Description
FEEDBACK_REQUIRED	Instagram returned a feedback dialog response. The account may need to acknowledge a policy notice in the official app.
VIDEO_TOO_LONG	The video supplied to an upload or story action exceeds the maximum allowed duration.
UNKNOWN	JxInsta received an error response it does not recognise. Log e.getMessage() and report the output to the JxInsta issue tracker.

IOException is separate

InstagramException does not wrap IOException. If a request fails at the socket level before any Instagram response is received, Java may throw a plain IOException rather than an InstagramException. Catch both independently if you need to handle low-level connectivity failures alongside API-level errors.

Methods in JxInsta that perform network I/O declare both InstagramException and IOException in their throws clause. If your method signature only declares InstagramException, the compiler will require you to also declare or catch IOException.

Log exception messages for debugging

When a default branch or an UNKNOWN reason is reached, always log the full exception message. The message often contains the raw error text returned by Instagram, which provides context that the Reasons enum alone cannot capture.

Use a structured logger rather than System.out.println in production code. Log both e.getReason() and e.getMessage() together so that filtering by reason in your log aggregator also captures the underlying detail.