• None
  • Manage Credentials
Launch IDE ↗

Stitch API

4.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:

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 }

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
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
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 may not yet be available for this bank, or the bank does not offer this feature.
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.