Error handling
- Last UpdatedJul 28, 2026
- 4 minute read
GraphQL errors can occur for various reasons, such as invalid queries, schema violations, or server-side issues. This section provides guidance on interpreting and handling these errors effectively.
First-response triage checklist
When a query fails, follow these steps:
-
Confirm whether HTTP status is 200, 400, 401/403, or 500.
-
Check whether data is present (partial success) even when errors exists.
-
Capture errors[].extensions.traceId for support and incident correlation.
-
Read errors[].extensions.resolution and apply corrective action.
-
Retry only when failure is transient (for example, a temporary dependency issue).
Common GraphQL errors
-
Syntax Errors: Occur when the query is malformed.
Example: Missing brackets or incorrect field names.
-
Validation Errors: Happen when the query does not match the schema.
Example: Requesting a field that does not exist.
-
Execution Errors: Arise during query execution, often due to server-side issues.
Example: Database connection failures.
Response codes
GraphQL typically returns a 200 OK HTTP status code for both successful and error responses, as errors are included in the response body. However, some implementations may use different status codes for specific scenarios:
-
200 OK: The request was processed, but execution errors could be present in the errors field of the response.
-
400 Bad Request: Used when the request is malformed and cannot be parsed (e.g., invalid filters in query).
-
401 Unauthorized / 403 Forbidden: Used when authentication or authorization fails.
-
500 Internal Server Error: Indicates a server-side failure that prevented the request from being processed.
Retry guidance
-
Do retry:
-
Temporary network failures.
-
Server-side transient failures (typically 5xx).
-
-
Do not retry unchanged requests:
-
Syntax or validation failures (400) until the query is corrected.
-
Authorization failures (401/403) until identity/permissions are corrected.
-
Recommended retry pattern for transient errors:
-
Use exponential backoff.
-
Add jitter.
-
Limit max attempts to avoid retry storms.
Error path values
GraphQL execution errors can include a path value that points to the response field that failed.
Example shape:
{
"errors": [
{
"path": ["entities", "items", 0, "inbound", 1, "stream"],
"message": "...",
"locations": [...],
"extensions": {...}
}
]
}
Use these conventions when reading path:
-
Integer segments are list indexes in items/collections.
-
String segments are response field names.
-
If your query uses aliases, the alias appears in path instead of the original field name.
Observed/expected path templates for Knowledge Graph V3 resolver-backed fields:
-
["entities"]
-
["linkedEntity"]
-
["events"]
-
["entity"]
-
["summarizeEntities"]
-
["summarizeEvents"]
-
["entities", "items", <n>, "inbound"]
-
["entities", "items", <n>, "relationships"]
-
["entities", "items", <n>, "relationships", <m>, "entity"]
-
["entities", "items", <n>, "relationships", <m>, "event"]
-
["entities", "items", <n>, "relationships", <m>, "type"]
-
["entities", "items", <n>, "relationships", <m>, "stream"]
-
["entities", "items", <n>, "relationships", <m>, "stream", "data"]
-
["entities", "items", <n>, "relationships", <m>, "stream", "metadata"]
-
["entities", "items", <n>, "relationships", <m>, "stream", "tags"]
-
["entities", "items", <n>, "componentTypes"]
-
["entities", "metadata", "componentTypes"]
-
["linkedEntity", "componentTypes"]
-
["events", "items", <n>, "relationships"]
-
["events", "items", <n>, "inbound"]
-
["events", "items", <n>, "type"]
-
["events", "items", <n>, "relationships", <m>, "entity"]
-
["events", "items", <n>, "relationships", <m>, "event"]
-
["events", "items", <n>, "relationships", <m>, "type"]
-
["events", "items", <n>, "relationships", <m>, "stream"]
-
["events", "items", <n>, "relationships", <m>, "stream", "data"]
-
["events", "items", <n>, "relationships", <m>, "stream", "metadata"]
-
["events", "items", <n>, "relationships", <m>, "stream", "tags"]
-
[<path to any Type object>, "baseType"]
-
[<path to any TypeRelationshipDefinition object>, "targetTypes"]
Errors without a path
Errors without path are expected in GraphQL.
-
Request-level failures (parse/validation) happen before field execution and typically do not have path.
-
Execution failures tied to a resolved field usually do have path.
-
A valid error object can be only message plus extensions (and optionally locations) with no path.
Dependency-origin errors (as of now)
Note: This section is a kindness list to help consumers debug quickly. It is an as-of-now snapshot and can drift over time. We do not own or maintain dependency-side error contracts in downstream services.
These are common dependency-origin error patterns currently surfaced by Knowledge Graph:
-
platform-graphdb-storage
-
Errors typically surface transitively through Graph Store responses (for example via extensions.errors).
-
-
platform-graph-store (entities/events)
-
503 message patterns:
-
Dependent service unavailable. (Entity Store)
-
Dependent service unavailable. (Event Store)
-
-
Other dependency details can flow through extensions.errors.
-
-
platform-types
-
Type-related request failures are surfaced as execution errors with standard extensions.
-
Example messages include class/type lookup failures.
-
-
platform-sds
-
Message pattern: Error retrieving SDS data. (may append dependency title)
-
Extensions typically include status, title, detail, type, traceId, resolution, instance.
Warning: Always check both the HTTP status code and the contents of the errors field in the response to determine the nature of the error.
-
Example of syntax error response
{
"errors": [
{
"message": "Error parsing query: Expected Name, found :; for more information see http://spec.graphql.org/October2021/#ObjectField",
"locations": [
{
"line": 2,
"column": 46
}
],
"extensions": {
"status": 400,
"title": "Bad Request",
"detail": "Your request could not be processed.",
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
"traceId": "bbd58f623769b1915f1b103c2f5f1443",
"resolution": "Verify that your request is correct. Try submitting your request again after correcting any issues.",
"instance": null,
"code": "SYNTAX_ERROR"
}
}
]
}
Example of validation error response
{
"errors": [
{
"message": "Argument 'input' has invalid value. In field 'filter': [In field 'where': [In field 'classLevel': Unknown field.]]",
"locations": [
{
"line": 2,
"column": 12
}
],
"extensions": {
"status": 400,
"title": "Bad Request",
"detail": "Your request could not be processed.",
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
"traceId": "7460f5dca8a3c0fc83538cc1235f1537",
"resolution": "Verify that your request is correct. Try submitting your request again after correcting any issues.",
"instance": null,
"code": "ARGUMENTS_OF_CORRECT_TYPE"
}
}
]
}
Example of execution error response
{
"errors": [
{
"message": "The ClassID value for ClassName 'CN_7' was not found.",
"extensions": {
"status": 400,
"title": "Bad Request",
"detail": "Your request could not be processed.",
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
"traceId": "a1de9caedf08ee7d3a21685e48bba681",
"resolution": "Verify that your request is correct. Try submitting your request again after correcting any issues.",
"instance": null
}
}
],
"data": {
"entities": {
"items": []
}
}
}
Partial data handling
GraphQL responses may include both data and errors in the same payload. Treat these as partial successes:
-
Render or process the valid subset from data where appropriate.
-
Surface a user-visible warning when critical fields failed.
-
Log full error details, including traceId, for diagnosis.
What to provide when escalating
Include the following when contacting support:
-
traceId from errors[].extensions.traceId
-
Query text (or a redacted equivalent)
-
Timestamp and environment
-
Service instance identifiers
-
Whether the issue is consistent or intermittent