Fix Intuit Ecosystem API errors

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

Step 1: Capture the intuit_tid value

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.

Step 2: Identify the error type

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 [List of possible GraphQL Error Code]
• Gateway errors: All other ###

Step 3: Fix errors

Fix gateway errors

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

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 401 errors, you may need to update your app’s access or refresh tokens.

See all gateway errors

Status code - Error details
302 - Resource redirect or resource has moved
401 - Unauthenticated access: application authentication failed due to invalid or expired tokens
403 - Forbidden access: authorization specific, application authorization failed due to insufficient user access role
403 - Resource not found: routing error, access or configuration on the  Gateway, or incorrect endpoint requested
405 - Method not allowed: attempt to request other than GET/POST requests
429 - Too many requests: request is throttled as it exceeded the throttle policy.
500 - Internal Server Error: missing POST body or other exceptions within application, or a service outage
502 - Bad Gateway: Infrastructure misconfiguration, propagates response from downstream, or a service outage
503 - Service unavailable: Outage
504 - Service timeout: Outage

Fix service errors

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.

See all service errors

200 - Authorization errors due to incorrect scope, or partial semantic errors
400 - GraphQL validation errors such as invalid or malformed requests and missing variables, or system errors

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 of an HTTP status code 400:

{
  "errors": [
    {
      "message": "cannot query field 'offset' on type 'Common_PageInfo!'",
      "extensions": {
        "type": "Common_PageInfo!",
        "field": "offset",
        "code": "INVALID_FIELD"
      }
    }
  ]
}

Here’s an example 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.

Error by error types

EmployeeCompensation :

CustomField :

Project error code :