Errors and Exceptions¶

aiographql-client distinguishes between two layers of failure:

Exceptions raised by the client when a request cannot be completed: validation failed, transport broke, server returned a non-2XX response, introspection failed, or codec failed.
GraphQL errors returned by the server in a successful HTTP response. These do not raise. They are on GraphQLResponse.errors alongside any partial data.

Exception Hierarchy¶

Every exception raised by the client derives from GraphQLClientException.

Exception	Raised by	Trigger
`GraphQLClientValidationException`	`query()`, `validate()`	Client-side validation against the introspected schema failed.
`GraphQLRequestException`	`query()`	The server responded with a non-2XX status. The originating response is attached as `.response`.
`GraphQLTransportException`	Any transport call	HTTP, TCP, TLS, or WebSocket failure. Subclass of `GraphQLClientException`; imported from `aiographql.client.exceptions`.
`GraphQLIntrospectionException`	`introspect()`, `get_schema()`	The endpoint refused introspection or returned an unusable schema.
`GraphQLCodecException`	Codec encode/decode	Variable encoding or response decoding failed for the configured codec.

Pre-flight Validation¶

When validate=True (the default on both GraphQLClient and GraphQLRequest), the client introspects the schema and validates the query before sending it. A query that fails validation is not sent to the server.

from aiographql.client import (
    GraphQLClient,
    GraphQLClientValidationException,
)

client = GraphQLClient(endpoint="https://api.example.com/graphql")

try:
    await client.query("{ doesNotExist { id } }")
except GraphQLClientValidationException as exc:
    # exc.args[0] is a multi-line summary of every validation error.
    log.warning("Bad query: %s", exc)

To skip validation (for example, when the server has introspection disabled), set validate=False on the request or on the client:

# Skip for one request:
request = GraphQLRequest(query="...", validate=False)

# Skip for the whole client:
client = GraphQLClient(endpoint="...", validate=False)

Transport and HTTP Errors¶

Network-layer failures raise GraphQLTransportException. HTTP responses outside the 2XX range raise GraphQLRequestException with the full response attached so the body and status can be inspected:

from aiographql.client import GraphQLRequestException
from aiographql.client.exceptions import GraphQLTransportException

try:
    response = await client.query(request)
except GraphQLRequestException as exc:
    # Non-2XX. The server's response is attached.
    log.error("HTTP %s: %s", exc.response.json, exc)
except GraphQLTransportException as exc:
    # DNS, TCP, TLS, WebSocket, etc.
    log.error("Transport failure: %s", exc)

For retry strategies around these exceptions, see Production Guide.

GraphQL Errors in a Successful Response¶

The GraphQL specification permits a server to return HTTP 200 with both data and errors. A successful HTTP call returns a GraphQLResponse and any server-reported errors are on response.errors.

response = await client.query(request)

if response.errors:
    for error in response.errors:
        log.warning(
            "GraphQL error at %s: %s",
            ".".join(map(str, error.path or [])),
            error.message,
        )

# Partial data is still available even when there are errors.
if response.data:
    process(response.data)

Each entry is a GraphQLError carrying message, path, locations, and any server-specific extensions. Unknown fields on the error object are preserved on a dynamically constructed subclass.

Introspection and Codec Errors¶

GraphQLIntrospectionException is raised when the client cannot build a schema from the endpoint, typically because introspection is disabled or the endpoint returned an error in response to the introspection query. The exception message includes the GraphQL errors that prevented schema construction.

GraphQLCodecException is raised by a configured GraphQLCodec when encoding request variables or decoding response data fails. The default codec raises this only for unrecoverable type mismatches; custom codecs may use it more liberally.

Choosing a Handling Strategy¶

Validation errors are programmer errors. Surface them in tests and CI. Do not retry them.
Transport and HTTP 5XX are transient. Retry with backoff (see Production Guide).
HTTP 4XX are caller errors (authentication, rate limit). Surface to the user; do not retry blindly.
GraphQL errors in a 200 response are domain errors. Inspect path and extensions to route them. Partial data may still be useful.
Introspection errors mean the schema is unavailable. Either set validate=False and accept the loss of pre-flight checks, or fail fast at startup.