Errors

Operations that can fail in ways a user can correct return a union instead of a single type. Selecting __typename tells you which variant came back, and each variant carries only the fields that make sense for it.

For example, updatePassword returns either a success variant or a variant describing why the password was rejected. For example, a weak password is a normal outcome of a password form, not an exception.

Always select __typename on a union result so you can branch on the outcome:

mutation UpdatePassword($input: UpdatePasswordInput!) {
  updatePassword(input: $input) {
    __typename
    ... on PasswordUpdated {
      success
    }
  }
}

Errors resulting from issues with the request – such as an expired or missing token, a request for an operation the token is not scoped for, or a malformed query – comes back in the top-level errors array with a null value for the affected field.

{
  "data": null,
  "errors": [
    {
      "message": "Unauthorized",
      "path": ["organizationMemberships"]
    }
  ]
}

Because the transport is GraphQL, these responses still return HTTP 200. Check the errors array rather than relying on the status code.

An expired Widget token surfaces as an authorization error. Request a fresh token from your backend and retry the operation once. See Authentication for details on how tokens are issued.