--- 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](/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": "", "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](/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. ## 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](/docs/grafana-cloud/observe-and-act/respond-to-incidents/reference/incident-api) - [Rate limits for Grafana IRM](/docs/grafana-cloud/observe-and-act/respond-to-incidents/reference/rate-limits)