Errors

Two error channels

1. Top-level errors arrive in the GraphQL errors array, identified by an error code, or as an HTTP status code. Example: HTTP 401 for a missing token. Authorization failures use this channel too, to stay consistent with the other authentication errors.
2. In-data errors arrive inside a mutation payload in an errors field. The rest of the payload is null or empty. Only some mutations return them, and only for errors you can act on, for example by fixing the input or retrying later. Every in-data error implements the Error interface and carries a message.

In-data error types

Type	Typical cause
ValidationError	An input value is missing or malformed.
ConnectedObjectNotFoundError	A referenced object, for example a template, does not exist.
IdempotencyKeyConflictError	The idempotency key was reused with different input.
RequestInProgressError	The same request is already in progress.
RecentIntelligenceReportExistsError	A report for this company and template was generated inside the cooldown window.
SubscriptionLimitExceededError	Your subscription does not allow more requests.
UnmodifiableError	The object cannot be changed in its current state.

NotFoundError and ForbiddenError still appear in some payload unions but are deprecated. Do not rely on them in-data.

Report generation errors

Report generation is asynchronous, so a generation failure is never in the request payload. Poll the report until generationStatus is ERROR, then read generationErrors on the report. Each entry has a message and a code; the schema scalar IntelligenceReportGenerationErrorCode lists the codes. See Report status and retrieval.

Sample: read the error type

errors is a union, so select fields through inline fragments: ... on Error for the message every error carries, and a fragment on a specific type for its own fields. Branch on __typename.

mutation RequestReport {
  requestCompanyIntelligenceReport(input: { companyId: "<company-id>", templateId: "<template-id>" }) {
    report {
      id
    }
    errors {
      __typename
      ... on Error {
        message
      }
      ... on ConnectedObjectNotFoundError {
        connectedObjectType
        connectedObjectId
      }
    }
  }
}

{
  "data": {
    "requestCompanyIntelligenceReport": {
      "report": null,
      "errors": [
        {
          "__typename": "ConnectedObjectNotFoundError",
          "message": "Template not found",
          "connectedObjectType": "IntelligenceReportTemplate",
          "connectedObjectId": "<template-id>"
        }
      ]
    }
  }
}