---
title: "Incident API errors | Grafana Cloud documentation"
description: "Reference for the error codes the Incident API returns, what each one means, and how to resolve it."
---

> For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt).

# Incident API errors

When a request to the Grafana IRM Incident API fails, the response body describes the error in a structured format. Use this reference to understand an error code and find out how to resolve it.

## Error response format

Error responses use the [RFC 7807 Problem Details](https://www.rfc-editor.org/rfc/rfc7807) format. For the errors listed on this page, the `type` field links to the matching entry. For other errors, `type` is `about:blank` and `title` is the HTTP status phrase, such as `Forbidden`.

The following example shows the response for an `orgs.not_initialized` error:

JSON ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```json
{
  "type": "https://grafana.com/docs/grafana-cloud/alerting-and-irm/irm/reference/errors#orgs.not_initialized",
  "title": "Incident Management Not Set Up",
  "status": 400,
  "detail": "Incident management in IRM hasn't been set up for this stack",
  "code": "orgs.not_initialized",
  "trace_id": "<TRACE_ID>",
  "hint": "Incident management in Grafana IRM hasn't been set up for this stack yet. Open the Incidents tab of IRM to finish setup, then retry the request.",
  "retryable": false,
  "error": "Incident management in IRM hasn't been set up for this stack"
}
```

The response contains the following fields:

Expand table

| Field       | Description                                                                               |
|-------------|-------------------------------------------------------------------------------------------|
| `type`      | A link to the entry for this error code on this page, or `about:blank`.                   |
| `title`     | A short summary of the error. It’s the same for every occurrence of an error code.        |
| `status`    | The HTTP status code.                                                                     |
| `detail`    | A description of this specific occurrence.                                                |
| `code`      | The error code. Use this field, not the message text, to handle errors in your code.      |
| `trace_id`  | An identifier for the request. Include it when you contact Grafana Support.               |
| `hint`      | Guidance on how to resolve the error.                                                     |
| `retryable` | Whether retrying the same request can succeed.                                            |
| `error`     | The same text as `detail`. It’s kept for clients that read the older error format.        |
| `context`   | Optional. Extra details about the error, such as the ID of the resource the request used. |

Some endpoints still return the older error format, which contains only an `error` field.

## Common errors

These errors aren’t specific to one type of resource.

### `common.internal_error`

HTTP status `500`. Usually retryable.

The server returned an unexpected error. Wait and retry the request. If the error continues, contact Grafana Support and include the `trace_id` from the response.

When a request that changes a role returns this error, `retryable` is `false` because the change might have been applied. Use `GetRoles` to check the current roles before you retry.

### `common.forbidden`

HTTP status `403`. Not retryable.

You don’t have access to the resource. For example, you get this error when you add a status update to a private incident and you don’t have a role in that incident. Grant the required access, then retry the request.

### `common.not_found`

HTTP status `404`. Not retryable.

The requested resource doesn’t exist. Check the IDs in the request.

### `common.validation_failed`

HTTP status `400`. Not retryable.

The request contains invalid input. Use the `detail` field to find the value to correct, then retry the request.

### `common.rate_limited`

HTTP status `429`. Retryable.

You sent too many requests. Wait before you retry. If the response includes a `Retry-After` header, wait at least that many seconds. For the limits that apply, refer to [Rate limits for Grafana IRM](https://grafana.com/docs/grafana-cloud/observe-and-act/respond-to-incidents/reference/rate-limits).

## Incident errors

These errors relate to incidents.

### `incidents.not_found`

HTTP status `404`. Not retryable.

No incident exists with the ID in the request. Check the incident ID.

## Role errors

These errors relate to incident roles.

### `roles.not_found`

HTTP status `404`. Not retryable.

No role exists with the ID in the request. Use `GetRoles` to list the available roles.

### `roles.name_conflict`

HTTP status `409`. Not retryable.

A role with this name already exists. Role names must be unique within your organization, including archived roles. Choose a different name.

### `roles.maximum_active_reached`

HTTP status `409`. Not retryable.

Your organization already has 5 active roles, which is the maximum. Archive or delete an active role before you create or unarchive another one.

### `roles.minimum_active_required`

HTTP status `409`. Not retryable.

Your organization needs at least two other active roles. Create or unarchive another role before you delete or archive this one.

### `roles.system_managed`

HTTP status `403`. Not retryable.

System-managed roles, such as **observer**, can’t be updated, archived, unarchived, or deleted, and you can’t reuse their names. You can still assign them to an incident by name.

## Severity errors

These errors relate to incident severities.

### `severities.not_found`

HTTP status `404`. Not retryable.

No severity exists with the ID in the request. Use `GetOrgSeverities` to list the available severities.

### `severities.level_conflict`

HTTP status `409`. Not retryable.

A severity with this level already exists. Levels must be unique within your organization, including archived severities. When you create a severity, choose a different level. When you unarchive a severity, archive the active severity that has the same level first.

### `severities.label_conflict`

HTTP status `409`. Not retryable.

A severity with this display label already exists. Labels must be unique within your organization, including archived severities. Choose a different label.

### `severities.maximum_active_reached`

HTTP status `409`. Not retryable.

Your organization already has 6 active severities, including **Pending**, which is the maximum. Archive or delete an active severity before you create or unarchive another one.

### `severities.system_managed`

HTTP status `403`. Not retryable.

The **Pending** severity is managed by IRM and can’t be archived or deleted. You can still edit its name, description, and icon, and assign it to incidents.

### `severities.in_use`

HTTP status `409`. Not retryable.

Incidents, open or closed, use this severity as their current severity or in a status update, so deleting it would change their history. Archive the severity instead to hide it from new incidents.

## Status errors

These errors relate to incident statuses.

### `statuses.not_found`

HTTP status `404`. Not retryable.

No status exists for the ID or slug in the request. Status configuration methods look up a status by ID. `UpdateStatus` looks up a status by slug, except for `active` and `resolved`. Use `QueryOrgStatuses` to list the available statuses.

## Field errors

These errors relate to custom fields and their select options.

### `fields.not_found`

HTTP status `404`. Not retryable.

No field exists with the UUID in the request. `AddLabelValue` returns this error when no label key exists with the key in the request. Use `GetFields` to list the available fields.

### `fields.option_not_found`

HTTP status `404`. Not retryable.

The field has no select option with the UUID in the request. Use `GetField` to list the options of the field.

### `fields.slug_conflict`

HTTP status `409`. Not retryable.

A field with this slug already exists. Slugs must be unique within your organization and domain, including archived fields. Choose a different slug.

### `fields.option_value_conflict`

HTTP status `409`. Not retryable.

The field already has a select option with this value. Option values must be unique within a field, including archived options. Choose a different value.

### `fields.version_conflict`

HTTP status `409`. Not retryable.

The field changed after you read it, so the `version` in your `UpdateField` request is out of date. Adding, updating, or deleting a select option also changes the version. Use `GetField` to read the current field and version, then apply your change again.

### `fields.system_managed`

HTTP status `403`. Not retryable.

Grafana generates this field and shares it across services, so the Incident API doesn’t let you change it. `UpdateField`, `DeleteField`, `UpdateFieldSelectOption`, and `DeleteFieldSelectOption` return this error for these fields, and `AddFieldSelectOption` can return it too.

### `fields.in_use`

HTTP status `409`. Not retryable.

Incidents, open or resolved, have a value for this field, so deleting it would remove those values from their history. A value that was cleared later still counts. Empty values that were never set don’t count, so you can delete a field that incidents only have empty values for. Incidents get an empty value like this for each field in their field group when they’re created. Archive the field instead to hide it from new incidents.

### `fields.option_in_use`

HTTP status `409`. Not retryable.

Incidents, open or resolved, have this select option as a value of the field, so deleting it would remove that value from their history. A value that was changed later still counts. `DeleteFieldSelectOption` returns this error, and so does `UpdateField` when the update leaves out an option in use, whether or not the option is archived. Archive the option instead to hide it from new incidents.

## Organization errors

These errors relate to how IRM is set up for your stack.

### `orgs.not_initialized`

HTTP status `400`. Not retryable.

Incident management in IRM hasn’t been set up for your stack yet. Setup finishes the first time someone opens the **Incidents** tab in Grafana IRM. This error usually happens when you call the Incident API from automation before anyone has opened the **Incidents** tab. Sign in to Grafana, open the **Incidents** tab once, and then retry the request.

## Related resources

- [Incident API reference](https://grafana.com/docs/grafana-cloud/observe-and-act/respond-to-incidents/reference/incident-api)
- [Rate limits for Grafana IRM](https://grafana.com/docs/grafana-cloud/observe-and-act/respond-to-incidents/reference/rate-limits)
