---
title: notice_error (Python agent API)
source: https://docs.newrelic.com/docs/apm/agents/python-agent/python-agent-api/noticeerror-python-agent-api
---

## Syntax

```py
newrelic.agent.notice_error(error=None, attributes={}, expected=None, ignore=None, status_code=None, application=None)
```

Records details of a Python exception as an error.

## Description

By default, the Python agent only reports unhandled exceptions. Use `notice_error` to record any Python exception as an error, which can then be found in the UI. If no parameters are provided, the details of the currently handled exception will be used.

You can record up to five distinct exceptions per [transaction](https://docs.newrelic.com/docs/accounts-partnerships/education/getting-started-new-relic/glossary#transaction), and up to 20 total exceptions across all transactions per [harvest cycle](https://docs.newrelic.com/docs/apm/new-relic-apm/getting-started/glossary#harvest-cycle).

When `notice_error()` is called within the context of a monitored web request or background task, the details of the exception will be reported against the application that the request or task is being reported to.

If called outside of the context of a monitored web request or background task, the call will be ignored unless the [`application`](https://docs.newrelic.com/docs/agents/python-agent/python-agent-api/application) keyword argument is provided and an application object corresponding to the application against which the exception should be recorded is provided. A suitable application object can be obtained using the `newrelic.agent.application()` function.

## Parameters

> #### 💡 TIP
>
> In almost all cases, `notice_error` will require no parameters.

| Parameter                                                                                                     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `error` _tuple, caught BaseException_                                                                         | Optional and rarely used. Either a tuple containing exception information `(exception_class, exception_instance, traceback)` returned from [`sys.exc_info()`](https://docs.python.org/3/library/sys.html#sys.exc_info) or a caught instance of `BaseException` from a `try` / `except` block. _Note: A traceback is always required, either as the third element of the exception tuple or as the `__traceback__` attribute on the instance of BaseException. Tuples from `sys.exc_info()` and BaseException instances from `try` / `except` blocks will already have a traceback._ |
| `attributes` _dict_                                                                                           | Optional. Custom attributes to add to the error event (in addition to any custom attributes already added to the transaction). If [high-security mode](https://docs.newrelic.com/docs/agents/manage-apm-agents/configuration/high-security-mode) is enabled, this will not work.                                                                                                                                                                                                                                                                                                    |
| `expected` _boolean_, _iterable[String]_, _callable(exception_class, exception_instance, traceback)->boolean_ | Optional. Errors to mark as expected can be passed in as an iterable of strings in the form `module:class`. This value can also be a callable or a Boolean indicating whether the error is expected. These errors will be reported to the UI but will not affect Apdex score or error rate.                                                                                                                                                                                                                                                                                         |
| `ignore` _boolean_, _iterable[String]_, _callable(exception_class_, _exception_instance, traceback)->boolean_ | Optional. Errors to ignore can be passed in as an iterable of strings in the form `module:class`. This value can also be a callable or a Boolean indicating whether the error should be ignored. Useful when certain types of exceptions should always be ignored and never recorded.                                                                                                                                                                                                                                                                                               |
| `status_code` _string_, _integer_, _callable(exception_class, exception_instance, traceback)_                 | Optional. The exception status code. This value can be a string, integer, or a callable that takes in exception information `(exception_class, exception_instance, traceback)` returned from [`sys.exc_info()`](https://docs.python.org/2/library/sys.html#sys.exc_info) and returns the status code as an integer.                                                                                                                                                                                                                                                                 |
| `application` _application object_                                                                            | Optional. If called outside of the context of a monitored web request or background task, the call will be ignored unless the [`application` object](https://docs.newrelic.com/docs/agents/python-agent/python-agent-api/application) is provided.                                                                                                                                                                                                                                                                                                                                  |

## Return values

None.

## Examples

### Simple example of reporting exceptions [#simple-example]

In a large majority of cases, you won't need to pass any parameters. You would just call the following where you want to report an exception:

```py
newrelic.agent.notice_error()
```

### Example using boolean [#boolean-example]

An example of `notice_error` using a boolean value. This indicates that an error should be expected.

```py
newrelic.agent.notice_error(expected=True)
```

### Call with a specific error, when multiple exceptions are active [#multiple-example]

```py
try:
    raise ValueError
except ValueError as first_exc:
    first_exc_tuple = sys.exc_info()
    try:
        raise RuntimeError
    except RuntimeError as second_exc:
        # To report an exception other than the most recently raised one
        newrelic.agent.notice_error(error=first_exc)
        # Or alternatively:
        # newrelic.agent.notice_error(error=first_exc_tuple)
```

When multiple exceptions are being handled at the same time, it is sometimes helpful to specify which exception you wish to report. This can be done by passing either the caught BaseException instance, or the tuple returned from calling sys.exc_info() when that exception was the active exception.

### Call with sys.exc_info() tuple and additional parameters [#complex-example]

An example of `notice_error` using `sys.exc_info()` data:

```py
def complex_ignore_errors(exc, val, tb):
   # do some logic here
   return False

newrelic.agent.notice_error(attributes={'my_special_exception': True}, ignore=complex_ignore_errors)
```

### Example using callback [#callback-example]

If you need to filter exceptions dynamically based on the attributes of a specific exception type, you can supply a callback function:

```py
def _ignore_errors(exc, value, tb):
    if instance(value, HTTPError):
        if value.status == 404:
            return True

newrelic.agent.notice_error(ignore=_ignore_errors)
```

If the exception is to be ignored/expected, set the return value for the callable to `True`. Return `False` if the exception should never be ignored/ expected regardless of any other checks, and `None` if subsequent checks and inbuilt rules should determine if the exception should be ignored/expected. A callback would normally return either `True` or `None`.