Error Handling – InterAction+™ Integration Answer Center

The API follows a structured approach to error handling, providing meaningful feedback when requests fail due to validation issues, business rule violations, or other unexpected conditions. While there are internal standards for returning errors, implementation may vary across different queries/mutations.

Response Behavior and HTTP Status Codes

In most cases, the API returns an HTTP 200 OK status even when an error occurs. This is because GraphQL errors are handled within the response body rather than through HTTP status codes. One of the exceptions to this is Status Code 429 - Too Many Requests, which is returned when rate limits are exceeded. Other status codes, such as those indicating authentication or availability issues, may be used.

Validation Errors

If the input does not meet expected requirements, such as when business rules are not followed, the response will include a list of validation errors. For mutations that perform input validation, the response typically follows this structure:

type UpdateActivityResult { 
  validationErrors: [ValidationErrors] 
  item: Activity
}

When validation fails, the item property is usually set to its default value, and the validationErrors property provides details about the issue. The message field offers actionable guidance.

Example: Validation Error Response

{
  "data": {
    "updateActivity": { 
      "item": null,
      "validationErrors": [
        {
          "message": "ActivityDate must be in the format 'yyyy-MM-dd HH:mm:ss'",
          "propertyName": "ActivityDate"
        }
      ]
    }
  }
}

General Errors

Errors that are not related to validation, such as internal processing failures, external service issues, or unexpected conditions, are returned in the errors collection of the GraphQL response.

These errors typically include the following:

Message: A description of the error.
Extensions: Additional metadata such as error codes or contextual information.

Example: General Error Response

{
  "data": {
    "addActivity": null
  },
  "errors": [
    {
      "message": "Method request failed with [220] Timestamp format 
must be yyyy-mm-dd hh:mm:ss[.fffffffff] for addActivity",
      "extensions": {
        "code": "APP_SERVER_METHOD",
        "data": {
          "activityId": "00-ebaa2c159c436a4a8e4c6bd086e33b2b-4927fca7e17ec948-00"
        }
      }
    }
  ]
}

Considerations

While the standards outlined above are generally followed, some queries/mutations may not yet fully align with them. Third-Party Client should handle both structured validation errors and general GraphQL errors gracefully.
Third-Party Client should always check the response body for error details rather than relying solely on HTTP status codes.

Search

InterAction+™ Integration Answer Center