Skip to main content

Error Handling

Errors in GraphQL are a little different to what you may be used to in a REST-style API.

GraphQL considers HTTP to be a separate layer in the network stack. This means that, for the most part, our API will return a 200 OK HTTP status, unless a network outage occurs.

Another important difference between REST and GraphQL is that a given query, in addition to succeeding and failing, may also partially fail.

Partial failures occur if a given subfield fails to resolve in a way that still respects the schema definition.

For example:

  • If a non-nullable field fails to resolve, the parent field will also fail.
  • If the same field were nullable, the parent would succeed, and the resolution failure would be added to the errors list.

Here is an example query that would return the JSON response below if the user had not granted the balances scope:

As you can see, the data field is still being returned with some other values, but now an errors field is being included in the results.

In the example above, the token being used contains the accounts scope and successfully returned the data associated with that scope. The token did not contain the balances scope and hence caused an error when trying to access the currentBalance field.

Error Object Structure

The errors field contains a list of errors. Each error shares a common format, but may also include additional fields.

The generally included parameters in an error object are:

FieldDescriptionType
messageAn expanded description of the errorString
locationsAn optional JSON array describing where in the query text the error occurredJSON Array
pathAn optional string array containing the logical path to the problematic fieldString Array
extensions.codeAn error code, describing the category of the errorError Code

Error Codes

Various error codes that you may encounter within the extensions.code field are:

Error CodeDescription
UNAUTHENTICATEDThe access token provided has expired, or is not present in the request's Authentication header.
FORBIDDENThe user did not authorize this application to perform a given action. You may need to request more scopes from this user. The extensions will usually contain the missingScopes or missingClaims field if the FORBIDDEN error is returned.
BAD_USER_INPUTInputs provided to the query failed validation rules.
REAUTHORIZATION_REQUIREDThe reauthorization guide dives into this error in more detail, but this indicates that reauthorization is required to complete the query, usually due to bank MFA.
RESULT_PENDINGA long running query has been submitted and the results are not yet available. Resubmit the query to poll for results
NOT_IMPLEMENTED_ERRORThis feature is not yet available for this bank.
GRAPHQL_PARSE_FAILEDThe query supplied to the server was malformed.
INTERNAL_SERVER_ERRORA catchall class for execution errors. May indicate that a given bank is not currently available, a subsystem is offline, or anything else that may have prevented resolution of a given field.
RESOURCE_UNAVAILABLEThis resource was not available - See the table below for possible reasons of unavailability.
VERIFICATION_ERRORAn error was encountered whilst verifying bank account details - See the BAVS integration details for possible failure reasons.

Resource Unavailable Reasons

The RESOURCE_UNAVAILABLE error, in particular, could occur due to one of the following reasons:

ValueDescriptionTransient/Retryable
bank_unavailableThe bank is temporarily down/unavailable.Yes
bank_field_temporarily_unresponsiveThis bank feature is temporarily down/unavailable.Yes
feature_unsupported_by_bankThis feature is not supported by this bank.No
bank_verification_requiredThe user has not submitted their FICA documents to the bank.No
unable_to_connectFailed to connect to the bank or a downstream service.Yes