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
errorslist.
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:
| Field | Description | Type |
|---|---|---|
| message | An expanded description of the error | String |
| locations | An optional JSON array describing where in the query text the error occurred | JSON Array |
| path | An optional string array containing the logical path to the problematic field | String Array |
| extensions.code | An error code, describing the category of the error | Error Code |
Error Codes
Various error codes that you may encounter within the extensions.code field are:
| Error Code | Description |
|---|---|
| UNAUTHENTICATED | The access token provided has expired, or is not present in the request's Authentication header. |
| FORBIDDEN | The 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_INPUT | Inputs provided to the query failed validation rules. |
| REAUTHORIZATION_REQUIRED | The 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_PENDING | A long running query has been submitted and the results are not yet available. Resubmit the query to poll for results |
| NOT_IMPLEMENTED_ERROR | This feature is not yet available for this bank. |
| GRAPHQL_PARSE_FAILED | The query supplied to the server was malformed. |
| INTERNAL_SERVER_ERROR | A 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_UNAVAILABLE | This resource was not available - See the table below for possible reasons of unavailability. |
| VERIFICATION_ERROR | An 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:
| Value | Description | Transient/Retryable |
|---|---|---|
| bank_unavailable | The bank is temporarily down/unavailable. | Yes |
| bank_field_temporarily_unresponsive | This bank feature is temporarily down/unavailable. | Yes |
| feature_unsupported_by_bank | This feature is not supported by this bank. | No |
| bank_verification_required | The user has not submitted their FICA documents to the bank. | No |
| unable_to_connect | Failed to connect to the bank or a downstream service. | Yes |