Stitch API

5.2. 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 may, in addition to succeeding and failing, also partially fail.

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

An 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:

1{
2 "errors": [
3 {
4 "message": "Token is missing the following scope: balances",
5 "locations": [
6 {
7 "line": 6,
8 "column": 7
9 }
10 ],
11 "path": [
12 "node",
13 "currentBalance"
14 ],
15 "extensions": {
16 "code": "FORBIDDEN",
17 "missingScopes": ["balances"]
18 }
19 }
20 ],
21 "data": {
22 "node": {
23 "id": "YWNjb3VudC9mbmIvMjUwNjU1LzYyNDI1MjM5NDcx",
24 "name": "FNB Premier Cheque Account",
25 "currentBalance": null
26 }
27 }
28}

As you can see, the data field is still being returned with some of the 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.

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

This table describes the meanings of common parameters in an error object:

Common Error Object Parameters
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

This table describes the error codes you may encounter within the extensions.code field:

Error Codes
ValueDescription
UNAUTHENTICATEDYour access token has expired, or is not present
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.
REAUTHORIZATION_REQUIREDThe reauthorization guide dives into this error in more detail, but this error 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 be 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 table below for possible reasons of a verification error.

Resource Unavailable Reasons

This table describes the reasons you may encounter within the RESOURCE_UNAVAILABLE error:

Resource Unavailable Reasons
ValueDescriptionTransient/Retryable
bank_unavailableThe bank is temporarily down/unavailableYes
bank_field_temporarily_unresponsiveThis bank feature is temporarily down/unavailableYes
feature_unsupported_by_bankThis feature is not supported by this bankNo
bank_verification_requiredThe user has not submitted their FICA documents to the bankNo

Linked Payments Errors

When initiating Linked Payments errors from the bank may be encountered, please see here on how to handle these.

BAVS Error Reasons

This table describes the reasons you may encounter within the VERIFICATION_ERROR error:

Verification Error Reasons
ValueDescription
invalid_account_typeThe provided bank account type is invalid
technical_errorAn error occured while making the verification request
invalid_branch_numberThe provided bank branch code is invalid
invalid_account_numberThe provided bank account number is invalid
instituition_not_supportedVerification of provided bank is not supported
invalid_account_number_lengthThe provided bank account number length is invalid
bond_account_not_allowedVerification of bond accounts is not supported