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.

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.

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