Fix GraphQL errors

If you encounter an error, the Intuit GraphQL API server returns an error message. These messages give you clues about the issue’s source and cause.

Server responses for gateway and service errors have an intuit_tid field in the header. Capture this field’s value. It will help our support team quickly find and address reported issues.

When requests from apps go to our servers, they first pass through a gateway layer. Then they pass through the GraphQL Service layer. Thus, there are two general types: gateway errors and service errors.

Review the HTTP Status Code (xxx). This tells you the error type:

• Service errors: 200 or 400
• Gateway errors: All other ###

Gateway errors are generated when requests hit our server’s gateway layer. They apply to the whole request and follow the gateway error response format.

1
2
3
4
5
6
7
8

  HTTP Status Code 401
  {
    "code": "AuthenticationFailed",
    "type": "INPUT",
    "message": null,
    "detail": "Malformed bearer token: too short or too long",
    "moreInfo": null
  }

In the server response, review the following fields:

• HTTP Status Code - Gives you the error code
• code - Tells you what went wrong
• detail - Tells you what to fix

Many gateway errors are self-explanatory. Some require a bit more digging. For 403 errors, you may need to adjust code for user roles. For 401 errors, you may need to update your app’s access or refresh tokens.

Service errors are generated when requests hit our server’s service layer.

Service errors only apply to a subset of requests, not the entire request. Responses follow the standard GraphQL service format.

Most service errors are in response to malformed queries, parsing problems, validation issues, or incorrect scopes. As a result, the server won’t authorize the request.

Here’s an example validation error:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

  "errors": [
      {
        "message":  "VAL-0001 Failed to fetch name for account with id#1",
        "locations": [ { "line": 6, "column": 7 } ],
        "path": [ "company", "account", 1, "name" ]
        "extensions": {
           "classification": "VALIDATION_ERROR"
        }
      }
  ]

Review the server response and use it as a guide. Each field gives clues for what failed, where, and how to fix it:

• Message — Description of the error.
• Extensions — Additional info and error codes:
  • code - Specific error code.
  • field - Field that has the error.
  • type - Entity that has the error.