Error Handling Overview
Error Handling
GraphQL error responses help identify failed operations, correct invalid input, and trace upstream service issues. The responses can include data, errors, or both. Always check both fields before treating a request as successful.
Error response format
A typical GraphQL response may include the following fields:
| Field | Description |
|---|---|
message | Failure summary returned for the operation |
path | GraphQL query or mutation field that failed |
extensions.code | Error category, such as BAD_USER_INPUT or UPSTREAM_ERROR |
extensions.serviceName | Domain service associated with the failure |
data | Operation result. This may be null, partially populated, or contain operation-specific error details |
Error Categories
Validation Errors
Validation errors occur when the request is successfully processed by the API but the input is missing, invalid, or does not meet business rules.
These errors usually use BAD_USER_INPUT.
Upstream validation errors
Upstream validation errors occur when an downstream service receives the request but rejects it because of a business or validation rule.
These errors may be included within the operation response payload.
Upstream service failures
Upstream service failures occur when a downstream service is unable to complete the request due to connectivity, timeout, or availability issues. These errors usually appear in the top-level errors array.