--- title: Errors API reference description: API reference for managing errors (faults) with endpoints to create, read, update, and delete error data. url: https://docs.honeybadger.io/api/faults/ --- Note A **fault** is synonymous with an **error**, in that it contains a collection of **notices** (individual error events) ## Get a fault list or fault details ```bash curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID/faults curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID/faults/ID ``` Returns a list of faults or a single fault for the given project with the following format: ```json { "action": "runtime_error", "assignee": { "email": "westley@honeybadger.io", "id": 1, "name": "Westley" }, "comments_count": 0, "component": "pages", "created_at": "2013-01-22T16:33:22.704628Z", "environment": "development", "id": 2, "ignored": false, "klass": "RuntimeError", "last_notice_at": "2013-02-11T19:18:31.991903Z", "message": "This is a runtime error", "notices_count": 7, "project_id": 1, "resolve_on_deploy": false, "resolved": false, "tags": ["internal"], "url": "https://app.honeybadger.io/projects/1/faults/2" } ``` The fault list can be filtered with a number of URL parameters: | Parameter | Description | | ----------------- | -------------------------------------------------------------------- | | `q` | A [search string](https://docs.honeybadger.io/guides/errors/search/) | | `created_after` | A Unix timestamp (number of seconds since the epoch) | | `occurred_after` | A Unix timestamp (number of seconds since the epoch) | | `occurred_before` | A Unix timestamp (number of seconds since the epoch) | | `limit` | Number of results to return (max and default are 25) | The fault list can be ordered with the order parameter in the URL, with the following possible values: | Value | Description | | ---------- | --------------------------------------------------------------- | | `recent` | List the errors that have most recently occurred first | | `frequent` | List the errors that have received the most notifications first | The default order is by creation time. If the search query affects the amount of matched notices, the `notices_count` field may not be accurate. For those cases, we add a `notices_count_in_range` field to the payload which reflects the notice counts with the query applied. ## Get a count of faults ```bash curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID/faults/summary ``` Returns a total count of all the errors for a project and counts of errors grouped by environment, resolution status, and ignored status. The counts can be filtered by these parameters: | Parameter | Description | | ----------------- | -------------------------------------------------------------------- | | `q` | A [search string](https://docs.honeybadger.io/guides/errors/search/) | | `created_after` | A Unix timestamp (number of seconds since the epoch) | | `occurred_after` | A Unix timestamp (number of seconds since the epoch) | | `occurred_before` | A Unix timestamp (number of seconds since the epoch) | For example, to get a count of open faults in production, you would use the `q` parameter to filter the results: ```bash curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID/faults/summary?q=environment%3Aproduction%20-is%3Aresolved%20-is%3Aignored ``` ## Update a fault ```bash curl -u AUTH_TOKEN: -X PUT -H 'Content-type: application/json' -d '{"fault":{"resolved":true}}' https://app.honeybadger.io/v2/projects/ID/faults/ID ``` The following fields can be updated: | Field name | Type | Description | | ------------------- | ------- | ---------------------------------------------------------- | | `resolved` | boolean | | | `ignored` | boolean | | | `assignee_id` | integer | | | `resolve_on_deploy` | boolean | Mark the fault to be resolved automatically on next deploy | Setting `resolved` or `ignored` to `true` in the same request takes precedence over `resolve_on_deploy`: the fault is resolved or ignored immediately and is not left marked for deploy. The current `resolve_on_deploy` state is also returned on each fault (see the fault details above). ## Delete a fault ```bash curl -u AUTH_TOKEN: -X DELETE https://app.honeybadger.io/v2/projects/ID/faults/ID ``` ## Get a count of occurrences for a fault ```bash curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID/faults/ID/occurrences ``` Provides the number of times errors have been encountered for a particular fault. ```json [ [ 1510963200, 1 ], [ 1511049600, 0 ], [ 1511136000, 0 ], [ 1511222400, 1 ], ... ] ``` The data can be filtered with these URL parameters: | Parameter | Description | | --------- | ------------------------------------------------------------ | | `period` | One of “hour”, “day”, “week”, or “month”. Defaults to “hour” | ## Pausing and unpausing faults You can pause notifications for a period of time or for the number of occurrences of a fault. This doesn’t affect the resolved/unresolved status. If a fault is resolved while paused, new occurrences will still mark it as unresolved — you just won’t be notified about it. For time-based pauses, notifications resume on the first occurrence received after the time period has elapsed. For count-based pauses, notifications resume on the occurrence that exhausts the count. In both cases, a notification will be sent even if the fault was already reopened by an earlier occurrence during the pause. ```bash curl -u AUTH_TOKEN: -X POST -H 'Content-type: application/json' -d '{"time":"day"}' https://app.honeybadger.io/v2/projects/ID/faults/ID/pause curl -u AUTH_TOKEN: -X POST -H 'Content-type: application/json' -d '{"count":100}' https://app.honeybadger.io/v2/projects/ID/faults/ID/pause ``` Valid values for `time` are “hour”, “day”, and “week”, and valid values for `count` are 10, 100, and 1000. You can clear the pause for a fault, or for all of a project’s faults: ```bash curl -u AUTH_TOKEN: -X POST https://app.honeybadger.io/v2/projects/ID/faults/ID/unpause curl -u AUTH_TOKEN: -X POST https://app.honeybadger.io/v2/projects/ID/faults/unpause ``` You don’t need to provide a request body for the unpause endpoints. The response body will be empty, and the status code will be 200. ## Bulk-resolving faults You can mark all faults for a project as resolved using this endpoint: ```bash curl -u AUTH_TOKEN: -X POST https://app.honeybadger.io/v2/projects/ID/faults/resolve ``` The faults to be resolved can be filtered with the URL parameter `q`, which is a [search string](https://docs.honeybadger.io/guides/errors/search/). Faults that are already resolved are skipped. On success the response body is empty. The status code tells you whether the update was completed or was queued: | Status | Meaning | | ------ | -------------------------------------------------------------------------------- | | 200 | Up to 1,000 faults matched. They were all resolved before the response was sent. | | 202 | More than 1,000 faults matched. The work was queued and runs in the background. | If the background work can’t be queued, the endpoint returns a 500 with an `errors` field, and nothing is resolved. Retry the request in that case. ## Linking faults to existing 3rd-party issues ```bash curl -u AUTH_TOKEN: -H 'Content-type: application/json' -d '{"channel_id":123, "data":{"number":42}}' -X POST https://app.honeybadger.io/v2/projects/ID/faults/ID/link ``` This associates an existing GitHub issue, Pivotal Tracker story, etc. with a fault. Once associated, the error detail page in the UI will include a link to the associated issue. The `channel_id` portion of the payload can be obtained from the [integrations](https://docs.honeybadger.io/api/projects#get-a-list-of-integrations-for-a-project) API endpoint. The `data` portion of the payload varies depending on which type of integration is being referenced: ### GitHub | Field name | type | Description | | ---------- | ------- | -------------------------------------------------------------------------------------------- | | `number` | integer | The issue number at the end of the issue URL: \*\* | ### Jira | Field name | type | Description | | ---------- | ------- | -------------------------------------------------------------------------------------------------- | | `id` | integer | The issue id at the end of the issue URL: \*\* | | `key` | string | The issue label: HB-123 | | `self` | url | The issue URL: | ### Pivotal Tracker | Field name | type | Description | | ------------- | ------- | -------------------------------------------------------------------------------------------------- | | `story_id` | integer | The story number at the end of the story URL: \*\* | | `project_id` | integer | The Pivotal Tracker project ID | | `pivotal_url` | url | The story URL: | ### Trello | Field name | type | Description | | ---------- | ------ | ------------------------------------------------------------------ | | `id` | string | The card ID, e.g. 60ca3275a482444bcaae2a8a | | `shortUrl` | url | Shortened version of the card URL: | This endpoint is also used to update an existing link (e.g., to change the issue number for a linked GitHub issue). ## Unlinking faults ```bash curl -u AUTH_TOKEN: -H 'Content-type: application/json' -d '{"channel_id":123}' -X POST https://app.honeybadger.io/v2/projects/ID/faults/ID/unlink ``` This removes the link to an associated GitHub issue, Pivotal Tracker story, etc. The `channel_id` portion of the payload can be obtained from the [integrations](https://docs.honeybadger.io/api/projects/#get-a-list-of-integrations-for-a-project) API endpoint. ## Get a list of notices ```bash curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID/faults/ID/notices ``` Returns a list of notices for the given fault with the following format: ```json { "created_at": "2013-02-11T19:18:31.123931Z", "environment": { "environment_name": "development", "hostname": "apollo.local", "project_root": { "path": "/Users/bob/code/crywolf" } }, "cookies" { ... }, "fault_id": 2, "id": "f78391e4-7789-49f0-888e-5f6c07a222f2", "url": "https://app.honeybadger.io/projects/1/faults/2/d23e5f62-747f-11e2-a65e-4f2716edc8b7" "message": "RuntimeError: This is a runtime error", "web_environment": { "CONTENT_LENGTH": "82", "CONTENT_TYPE": "application/x-www-form-urlencoded", "HTTP_USER_AGENT": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_7_4) AppleWebKit/537.4 (KHTML, like Gecko) Chrome/22.0.1229.79 Safari/537.4", ... }, "request": { "action": "runtime_error", "component": "pages", "context": { "cart_id": "8EF99AFC-B4DB-4FC5-A92A-9A6F86ABD364" }, "params": { "_method": "post", "a": "1", "action": "runtime_error", "authenticity_token": "...", "b": "2", "controller": "pages" }, "session": { "_csrf_token": "...", "session_id": "..." }, "url": "http://example.com/pages/runtime_error?a=1&b=2", "user": { "email": "foo@bar.com", "id": 1 } }, "backtrace": [ { "number": "4", "file": "/Users/westley/code/crywolf/app/controllers/pages_controller.rb", "method": "runtime_error" }, ... ], "application_trace": [] } ``` The notice list can be filtered with these URL parameters: | Parameter | Description | | ---------------- | ---------------------------------------------------- | | `created_after` | A Unix timestamp (number of seconds since the epoch) | | `created_before` | A Unix timestamp (number of seconds since the epoch) | | `limit` | Number of results to return (max and default are 25) | The notice list is always ordered by creation time descending. ## Get a list of affected users ```bash curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID/faults/ID/affected_users ``` Returns a list of the users who were affected by an error: ```json [ { "user": "bob@example.com", "count": 4 }, { "user": "ann@example.com", "count": 1 } ] ``` The data can be filtered with the URL parameter `q`, which is a [search string](https://docs.honeybadger.io/guides/errors/search/). --- ## Try Honeybadger for FREE Intelligent logging, error tracking, and Just Enough APM™ in one dev-friendly platform. Find and fix problems before users notice. [Start free trial](https://app.honeybadger.io/users/sign_up) [See plans and pricing](https://www.honeybadger.io/plans/)