InstagramException — error handling class reference

API reference for InstagramException in JxInsta — getReason() and all Reasons enum values covering auth, rate limiting, content errors, and network failures.

InstagramException is the single checked exception type thrown throughout both the web and mobile modules. Every API method that communicates with Instagram declares throws InstagramException. Rather than relying on exception messages alone, the library maps each failure mode to a member of the Reasons enum, allowing call sites to branch on the type of failure without parsing strings.

Package

com.jxinsta.mobile.InstagramException

The same class is mirrored at com.jxinsta.web.InstagramException in the web module.

---

Constructor

InstagramException(String message, Reasons reasons)

Creates a new exception with a descriptive message and a categorised reason.

message · String · required

Human-readable description of the error, typically prefixed with a key such as "BadPassword: " followed by the raw JSON from Instagram.

reasons · Reasons · required

The Reasons enum constant that categorises the failure.

---

Static factory

wrap(JSONObject lastJson, int statusCode)

Inspects an Instagram error response and maps it to the most specific Reasons constant. This is used internally throughout the library; you do not normally call it directly, but it is part of the public API.

// Internal usage pattern:
throw InstagramException.wrap(responseJson, response.code());

lastJson · JSONObject · required

The JSON body returned by Instagram’s API in the error response.

statusCode · int · required

The HTTP status code of the response (e.g. 400, 403, 429).

Returns — a fully constructed InstagramException with an appropriate Reasons value.

---

Methods

getReason()

Returns the categorised reason for the exception.

try {
    client.getProfile("someuser");
} catch (InstagramException e) {
    if (e.getReason() == InstagramException.Reasons.PRIVATE_ACCOUNT) {
        System.out.println("This account is private.");
    } else {
        throw e;
    }
}

Returns — InstagramException.Reasons

---

Reasons enum

All constants are members of InstagramException.Reasons.

Authentication

INVALID_CREDENTIAL · Reasons

The credentials provided are not valid. Covers cases where the combination of username and password is rejected at the account level.

INVALID_LOGIN_TYPE · Reasons

Instagram rejected the login attempt because the login method is not permitted for this account type.

INCORRECT_PASSWORD · Reasons

The password is wrong. Also raised when Instagram suspects the IP is on a block list — the exception message includes a suggestion to change IP address.

INCORRECT_USERNAME · Reasons

The supplied username does not match any Instagram account.

LOGIN_EXPIRED · Reasons

The session has expired or been invalidated. Re-authenticate to obtain a fresh session.

CHECKPOINT_REQUIRED · Reasons

Instagram requires the user to complete a security challenge (e.g. email/SMS verification) before the action can proceed.

TWO_FACTOR_REQUIRED · Reasons

Two-factor authentication is enabled on the account and must be satisfied before login completes.

CSRF_AUTHENTICATION_FAILED · Reasons

The CSRF token attached to the request was missing, expired, or did not match.

UNKNOWN_LOGIN_ERROR · Reasons

An unrecognised error occurred specifically during the login flow.

---

Rate limiting

RATE_LIMITED · Reasons

Too many requests were sent in a short period (“Please wait a few minutes”). Back off and retry after a delay.

THROTTLED · Reasons

HTTP 429 response. The server is actively throttling requests from this client.

---

Content and targeting

FORBIDDEN · Reasons

HTTP 403 — the session does not have permission to perform the requested action.

FEEDBACK_REQUIRED · Reasons

Instagram requires explicit user feedback or acknowledgement before the action can proceed (HTTP 400, feedback_required message).

SENTRY_BLOCK · Reasons

The account or IP has been flagged by Instagram’s Sentry system and is blocked from performing this action.

VIDEO_TOO_LONG · Reasons

The video submitted for upload exceeds Instagram’s maximum allowed duration.

PRIVATE_ACCOUNT · Reasons

The target account is private and the authenticated user is not an approved follower.

INVALID_TARGET_USER · Reasons

The user ID supplied as the target of an action does not correspond to a valid account.

INVALID_MEDIA_ID · Reasons

The media ID provided does not refer to any known post.

MEDIA_UNAVAILABLE · Reasons

The requested media has been deleted, made private, or is otherwise not accessible.

USER_NOT_FOUND · Reasons

The specified user could not be found (e.g. when fetching followers for a non-existent account).

PROXY_ADDRESS_BLOCKED · Reasons

Instagram has blocked the IP address of the proxy being used. Replace the proxy with a private, non-shared address.

---

Network and protocol

IO · Reasons

A low-level network I/O error occurred (e.g. connection refused, socket timeout, DNS failure).

PARSING_FAILED · Reasons

The response body could not be parsed as valid JSON, typically indicating an unexpected HTML error page.

BAD_REQUEST · Reasons

A malformed or otherwise invalid request was sent to the server (HTTP 400 fallback when no more specific reason can be determined).

NOT_FOUND · Reasons

HTTP 404 — the requested API endpoint does not exist or the resource was not found.

REQUEST_TIMEOUT · Reasons

HTTP 408 — the server did not receive a complete request within the timeout window.

---

Catch-all

UNKNOWN · Reasons

The error could not be mapped to any of the specific categories above. Inspect getMessage() for the raw response details.