Troubleshooting Cato API Calls

This article provides troubleshooting suggestions for common errors that can occur when you use the Cato to run an API query with API tools and software. For example, Altair and Postman.

Issues related to API scripts and coding aren't supported.

Required API Arguments

These are the arguments that you must include in the API query. When you remove an optional argument from the API query, the default value is used.

• accountMetrics query
  • id - account ID
  • timeframe - time frame of data that the query returns
  • groupDevices - For multiple sites, and sites with multiple Sockets, combine the analytics into a single Socket (for boolean value true)
• accountSnapshot query
  • id - account ID

Common GRAPHQL_PARSE_FAILED Errors

This section explains some common examples for error messages related to the Cato GraphQL schema.

Message: Unexpected )

There is an extra parenthesis in the query. Often this error is caused when you don't provide a boolean value for an argument. For example, groupInterfaces: , instead of groupInterfaces: true,

Message: Expected Name, found <character>

The JSON file isn't formatted correctly. The message shows a character that is related to the missing or extra character. For example, Expected Name, found ( for the argument accountSnapshot((id: 42). The correct format for this argument is accountSnapshot(id: 1941)

Message: Expected Name, found <Invalid>

The error message indicates that there is an with an invalid value.

For example, the timeFrame argument (accountMetrics) in the Cato API uses quotation marks for the ISO 8601 date and time standard, timeFrame: "last.P1D" is correct and timeFrame: last.P1D produces this error.

Common GRAPH_QL_VALIDATION_FAILED Errors

This section explains some common examples for error messages related to the incorrect format for arguments in the query.

Message: Expected type String!, found <number>

The error message indicates that an argument has an invalid value, usually related to the argument format.

For example, the sites ids argument (accountMetrics > sites) is a STRING, so you must use quotation marks for the value, ids: ["4242"] is correct and ids:[4242] produces this error.

Message: Expected type Int!, found \"<number>\"

The error message indicates that an argument has an invalid value, usually related to the argument format.

For example, the sites ids argument (accountSnapshot > sites) is an INT, so you must NOT use quotation marks for the value, ids: [2626] is correct and ids:["2626"] produces this error.

API Error Messages

This section explains common error messages that aren't specifically related to Cato GraphQL schema or format.

Message: authentication error

There is a problem with the API key for your account. Suggested solutions:

• In the Cato Management Application (System > API Access Management), make sure that the API key you are using is still valid. The key is deleted when it's revoked.
• Confirm that the key is configured correctly in the HTTP header settings for the API query software: x-api-key <key value>
• If the problem continues, generate a new API key and add it to the API query software

Message: cannot separate devices (groupDevices = false) when multiple sites are selected

The value for the groupDevices argument (accountMetrics) must be true when the query includes multiple sites.

General API Error when Running Scripts during Maintenance Window

During the maintenance window (generally every other Sunday), Cato upgrades the API server and it can be temporarily unavailable for up to two minutes. If you are running recursive API scripts, then during a maintenance window the script may fail and return an error. There is no impact on the data for your account.

For up to date information about the scheduled maintenance windows and the status of the Cato Cloud, see https://status.catonetworks.com/.

General API Error for Timeout with the API Server

If there is a delay for more than 40 seconds for an API query, then there is a timeout with the API server and you need to run the query again. We recommend that you include a retry mechanism with an API script for your Cato account. This mechanism should include at least two retry attempts and wait at least 30 seconds between each retry attempt.