<!-- llms.txt: https://workos.com/llms.txt -->

# Errors

## Expected failures are result variants

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`](https://workos.com/docs/widgets-api/authentication/update-password) 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:

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

## Unexpected failures are GraphQL errors

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.

```json
{
  "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.

## Handling expired tokens

An expired Widget token surfaces as an authorization error. Request a fresh token from your backend and retry the operation once. See [Authentication](https://workos.com/docs/widgets-api/authentication-tokens) for details on how tokens are issued.