Documentation Grafana Cloud Observe and act Manage on-call and incidents Reference Incident API errors

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 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

{
  "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:

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.

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.

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
• Rate limits for Grafana IRM