Error Handling

GraphQL provides detailed error messages that make debugging easier and more transparent. One of its key advantages is support for partial success - even if part of a query fails, the rest can still return valid data. Unlike REST, GraphQL errors are not tied to HTTP status codes, allowing for more nuanced and informative responses directly within the API payload.

Unlike REST APIs, which often return error details automatically in the response body, GraphQL only returns fields that you explicitly query. This means you must include error fields in your request to receive this information. This approach ensures that applications handle errors consistently and predictably.

For example

errors {
  message
  name
  field
}

The API provides two types of errors, expected and unexpected.

Expected Errors

Expected errors occur when your request is valid, but the system cannot complete the action because certain rules, permissions, or conditions have not been met. These errors are a normal part of API operation and are designed to provide clear, actionable information about what went wrong. They are returned in a structured, strongly typed format within the main data section of the response. Because GraphQL only returns fields that you explicitly query, you must include error fields in your request to receive this information. This approach ensures that applications handle errors consistently and predictably.

Each expected error includes:

A specific error type.
A plain‑language message explaining the issue.

This helps you quickly determine whether the problem is related to access, account limits, or information that is correctly formatted but not valid for the action. Because the format is predictable, applications can guide you directly toward the appropriate next step, such as adjusting input values or confirming the required permissions.

For example, if you try to create a static tag for an organization that you do not have access to (or the organization does not exist), the API returns an expected, typed error. To retrieve this error in GraphQL, you must include the error fields in your operation, for example:

mutation StaticTagCreate($input: StaticTagCreateMutationInput!) {
  staticTagCreate(input: $input) {
    errors {
      __typename
      ... on StaticTagCreateNotPermittedError {
        message
        name
        organizationId
      }
      ... on StaticTagAlreadyExistsError {
        message
        name
      }
      ... on StaticTagInvalidNameError {
        message
        name
      }
    }
    item {
      id
      name
    }
  }
}

{
  "data": {
    "staticTagCreate": {
      "errors": [
        {
          "__typename": "StaticTagCreateNotPermittedError",
          "message": "User is not permitted to create this tag.",
          "name": "tag-name",
          "organizationId": "12345-abcd-1234-abcd-1234"
        }
      ],
      "item": null
    }
  }
}

Characteristics

Appears in the main response data Expected errors are returned within standard data, not as system‑level failures.
Clearly typed categories Each error includes a specific, recognizable type to help you identify the issue quickly.
Clear explanations Error messages describe the cause in straightforward terms.
Supports corrective action The structure makes it easy for applications to offer helpful guidance or next steps.

When you might see these errors

Access limitations The item you’re trying to view or modify isn’t available, or your account doesn’t have the required permissions.
Account or system rules The action doesn’t meet the specific requirements, constraints, or limits associated with your account or the resource.
Data conflicts Your input is valid in format, but it cannot be used for this request - for example, selecting a date in the past or choosing an option that isn’t allowed for the current configuration.

How to handle expected errors

Review the message Read the specific error type to understand which condition or requirement wasn’t met.
Update your request Adjust your input or settings based on the feedback provided.
Check permissions Confirm that your account has the necessary access for the operation you’re attempting.

Unexpected Errors

Unexpected errors occur when the system runs into a problem it did not anticipate, such as a temporary interruption, processing failure, or service issue. These errors are not caused by your request - they happen when the platform is unable to complete the operation.

Because these issues are unplanned, the system may only provide a general message rather than a detailed explanation. Unexpected errors appear as system‑level messages instead of typed, categorized errors. They typically contain limited information and usually indicate a temporary condition that can be resolved by retrying the request once the system stabilizes.

For example, an operation may be correctly formatted but still trigger an unexpected error if it is too complex to process, causing a temporary timeout. In these cases, where the error fields are included in your operation, the system returns a general error message.

{
  "data": null,
  "errors": [
    {
      "message": "An unexpected error occurred.",
      "extensions": { "code": "INTERNAL_SERVER_ERROR" }
    }
  ]
}

Characteristics

Not returned as typed errors Unexpected errors appear as standard system messages rather than structured, categorized results.
Caused by technical issues They are the result of system interruptions, processing failures, or internal service problems - not the content of your request.
Limited detail available Because the system was not prepared for the issue, the message may provide only basic information, such as a generic “Error” or “Internal error occurred.”

When you might see these errors

Conflicting actions happening at the same time Two processes attempt to update or modify the same item simultaneously, creating a situation the system did not anticipate.
Unexpected or inconsistent data states A resource may be partially updated or missing required information due to a prior operation that did not finish cleanly, causing the system to respond unpredictably.
Recent configuration changes If unexpected errors start occurring after a permission update, or configuration change, check whether a recent update introduced a conflict or temporarily inconsistent state.

How to handle unexpected errors

Wait and retry Many unexpected errors resolve on their own. Try the request again after a short pause.
Verify service status Check your system status page or internal logs to determine whether there is a known outage or maintenance event.
Test using a simplified request Remove optional fields or reduce the request to the minimum required inputs. If the simplified request succeeds, the issue may be triggered by a specific parameter or payload structure.

Request Help

If the problem persists, open a Support ticket so we can investigate further.

To contact Support:

From the top‑right menu (☰), select Support.
Sign in to N‑ableMe.
Submit your support request.