Errors

When any method invoked against the ngrok API returns an error, a Exception of ngrok.Error will be raised.

The exception includes details that will allow you to robustly handle any error returned by the API. The ngrok.Error.error_code field allows you to handle any error in the ngrok system. Consult our API Errors Documentation for the list of error codes the API may return.

Handling Errors

If the API returns an unexpected 404, a ngrok.NotFoundError will be raised. Ensure that you check for it first because it is a subclass of ngrok.Error.

try:
    c.ip_policies.get(id)
except ngrok.NotFoundError as e:
    c.ip_policies.create(action="deny")
except ngrok.Error as e:
    # something else happened

Other validation errors are best distinguished by their error code. Consult our documentation for the list of all ngrok error codes.

try:
    c.ip_policies.create(action="something invalid")
except ngrok.Error as e:
    if e.error_code == "ERR_NGROK_1410":
        # handle a specific condition
    else:
        raise

If the ngrok API fails with an undefined response or there is some kind of network error, there are no guarantees about the type of exception thrown at that point it is best to use a naked except block or to catch a RuntimeError.

try:
    c.ip_policies.create(action="something invalid")
except RuntimeError:
    # an unexpected network error that you could retry

Exception Classes

exception ngrok.Error(error_code, message, http_status_code, details)[source]

Raised by failed ngrok API operations.

This class encapsulates details about the error to make it simple for callers to introspect the error and take action on it.

Parameters
  • error_code (Optional[int]) – The unique ngrok error code indicating why the operation failed.

  • message (str) – Human-readable string explaining the error.

  • http_status_code (int) – HTTP status code returned by the server.

  • details (Any) – Arbitrary additional details about the error.

property operation_id

OperationID returns the unique trace ID assigned by ngrok to this API request.

exception ngrok.NotFoundError(error_code, message, http_status_code, details)[source]

Raised if the http_status_code of an API operation is 404. This is a separate class to make this common condition easier to handle.