Skip to main content

Error handling

GraphQL queries and mutations require different error handling. We made this design decision as we expect:

  • queries: to generally succeed, as the three most common issues are usually unauthenticated, forbidden, or an internal server error. In the case of unauthenticated and forbidden, the API keys are invalid, while internal server errors should be retried.
  • mutations: to return errors regularly as part of the normal business flow due to invalid inputs. Errors need to be parsed and displayed to an end user so the input can be fixed.

Handling error in queries​

Query errors aren't modeled in the GraphQL schema, but rather use GraphQL's error extensions.

If the query returns the value null, that typically indicates that the entity is not found (equivalent to an HTTP 404 in a REST API).

The list of error extensions that can be returned by queries:

  • GRAPHQL_PARSE_FAILED: The GraphQL operation string contains a syntax error. The request should not be retried.
  • GRAPHQL_VALIDATION_FAILED: The GraphQL operation is not valid against the schema. The request should not be retried.
  • BAD_USER_INPUT: The GraphQL operation includes an invalid value for a field argument. The request should not be retried.
  • UNAUTHENTICATED: The API key is invalid. The request should not be retried.
  • FORBIDDEN: The API key is unauthorized to access the entity being queried. The request should not be retried.
  • INTERNAL_SERVER_ERROR: An internal error occurred. The request should be retried. If this error persists, please get in touch at help@plain.com and report the issue.

Handling errors in mutations​

All mutations return with a Output type that follow a consistent pattern of having two optional fields, one for the result and one for the error. If the error is returned then the mutation failed.

type Example {
  data: String!
}

type ExampleOutput {
  # example is the result of the mutation, is only returned if the mutation succeeded
  example: Example
  # if error is returned then the mutation failed
  error: MutationError
}

Mutation errors are typed and can be handled by inspecting the MutationError object.

MutationError​

  • message: an English technical description of the error. This error is usually meant to be read by a developer and not an end user.
  • type: one of VALIDATION, FORBIDDEN, INTERNAL. See MutationErrorType for a description of each value.
  • code: a unique error code for each type of error returned. This code can be used to provide a localized or user-friendly error message. You can find the list of error codes documented.
  • fields: an array containing all the fields that errored
    • field: the name of the input field the error is for
    • message: an English technical description of the error. This error is usually meant to be read by a developer and not an end user.
    • type: one of VALIDATION, REQUIRED, NOT_FOUND. See MutationFieldErrorType for a description of each value.

Reference: Mutation Error Object