Partial response and error handling

GraphQL responses can mix payloads and errors. In xDI, the GraphQL component controls error tolerance with properties in the integration template.

Handling partial and error responses

In GraphQL metadata, the JSON root node can contain both data and errors branches to represent successful responses and errors. The errors branch is an array of error objects that provide details about any issues encountered during the execution of the GraphQL operation. The error objects must follow the GraphQL specification.

Like successful responses, errors create output data that you can map to a datastore, or use to control a process. If you have configured error tolerance in the integration template, you can use data from both successful and errored queries.

Error tolerance in mappings

The GraphQL integration template exposes two parameters that controls when mappings should fail, based on the number of partial errors returned in GraphQL responses:

  • Partial response error tolerance, by query: controls mapping failure for individual queries. If one query in a GraphQL operation returns more partial errors than the configured threshold, the mapping fails.

  • Partial response error tolerance, overall: controls mapping failure based on all GraphQL queries. If the total number of partial errors across all queries in the operation exceeds the configured threshold, the mapping fails.

Both parameters accept integer values that determine the error tolerance level:

  • Negative integers: tolerate all partial errors. The mapping is always in a Success state.

  • 0 (default): mapping fails at the first partial error.

  • 1 and above: mapping fails when more partial errors occur than this value.

Error tolerance with query variables

When using query variables in mappings, the by query tolerance applies to each time a query is executed. If you map multiple rows to a query with variables, each row triggers a separate query execution, and each execution can tolerate up to the configured number of errors.

The behavior depends on how many queries the mapping executes:

  • If your mapping maps one row to the GraphQL query, one query is executed, and the by query tolerance applies to that single query.

  • If your mapping maps multiple rows (for example, from a database table), multiple queries are executed (one per row). The by query tolerance applies to each query execution individually.

  • The overall tolerance applies to all errors across all queries in the entire mapping execution.

Example: Multiple queries with error tolerance

Consider a mapping that reads 5 customer IDs from a database and executes a GraphQL query with variables for each ID:

  • Configured tolerance by query: 1

  • Configured tolerance overall: 2

The mapping executes 5 separate GraphQL queries. Each query execution can tolerate 1 error. However, if 3 errors occur across all query executions, the mapping reaches the overall limit and fails immediately.

For more information about variables, see Query variables.