Search

API Troubleshooting

Andrew Anderson
Andrew Anderson
  • Updated

This article is primarily dedicated to identifying and resolving issues, errors, bugs, etc that likely are relevant in various ways to Athennian API integrations (directly or indirectly). It is a technical companion document mostly for the API Reference Addendum.

There are several sections on this page including: Athennian API, platform GUI, Microsoft Power Automate, etc.

Prefer learning more with your Microsoft Copilot or other AI assistant? No problem! ▶️ Here you'll find a quick video demo with examples of how this can be done for most of our automation solutions, and more here. 

 

Athennian API

General Steps

API

When troubleshooting issues, providing the details below generally clarifies or speeds up resolutions.

  1. Priority
    1. Do you need it fully resolved by a certain time (zone)?
    2. Please describe if/how you are impacted or blocked exactly.
  2. Replication
    1. API request
      1. Entire cURL text (endpoint URL, query, etc). Ideally in Postman format.
      2. API key
        1. (text format) Usually helpful, but only required when replication requires specific configuration or data states.
  3. Context
    1. When did it last work (timezone)?
    2. What is it and is it not impacting specifically (exact data categories, sandbox vs production links, etc)?
    3. Are there any changes that have taken place on your side that might have caused this?

GUI

Graphical User Interface (standard Athennian platform)

  1. Switch off the New Experience toggle.
  2. Reselect the value via the platform GUI.
  3. Log into Athennian with a fresh session via Google Chrome incognito or alternative, etc.
  4. Review your API inputs to see if there are now better options available.

Microsoft Power Automate

Click here for all relevant documentation.

Specific Errors

Here we publish the most important validation response codes and primary context required to understand or resolve them as appropriate.

As is likely industry standard, our front-end error codes may represent different error codes on the back-end (HOOT-8646). This is primarily for security purposes.

Also, in standard GraphQL, requests can partially succeed / fail unlike more traditional API types. Therefore it's recommended that the body of each response request be considered in error handling.

For example here is an example of a 200/403 response with a partial block. However, in some cases data may be returned etc.

"status": "CLIENT_ERROR",
"message": "403 - {\"status\":403,\"msg\":\"ERROR - Creating Person User is not authorized for CREATE\",\"data\":null,\"actionTaker\":{\"_id\":\" .... redacted
...
{
"status": "CLIENT_ERROR",
"message": "undefined has no access to the following access group IDs: ... redacted
....
],
"data": {
...more data redacted here

GUI

Invalid Code

Try the following to resolve if you encounter this for fields like NAICS Code (ticket # HOOT-8580):

  1. Switch off the New Experience toggle.
  2. Reselect the value via the platform GUI.
  3. Log into Athennian with a fresh browser.
  4. Review your API inputs to see if there are now better options available.

Miscellaneous

Send Request

The error below can be caused by a Host URL endpoint typo (apil -> api).

Could not send request
Error: getaddrinfo ENOTFOUND apil.athennian.com

200/200

OK Example below.

{
"data": {
accessGroups: [redacted for this example],
"OrCustomAccessGroupQueryLabel": [redacted for this example]
}
}

200/403

Make sure the profile, group or other data you are running in your query is still available to your key.

Postman 1: Reading

"status": "CLIENT_ERROR",
"message": "403 - {\"type\":\"ERR\",\"msg\":\"ERROR - Not authorized for action on record\",\"err\":{\"name\":\"UserPermissionCheckError\"}}"
}
],
"data": null

Postman 2: Writing

"status": "CLIENT_ERROR",
"message": "403: Forbidden"
}
],
"data": null

OR

"status": "CLIENT_ERROR",
"message": "403 - {\"status\":403,\"msg\":\"ERROR - Creating Person User is not authorized for CREATE\",\"data\":null,\"actionTaker\":{\"_id\":\" .... redacted
...
{
"status": "CLIENT_ERROR",
"message": "undefined has no access to the following access group IDs: 665a0fd...
...
],
"data": {
...

200/409

Make sure you are passing valid variable value lengths, formats, etc.

Postman 1:

"status": "CLIENT_ERROR",
"message": "409: Conflict"
}
],
"data": {
"accessGroups": null

200/Server

Some datapoints become required (ie, country) only when other optional fields are used (ie, region).

PA 1:

"status": "SERVER_ERROR",
"message": "The region US-WA is not available in current country undefined."
...
"data": {
"createEntity": null

400/400

To resolve this error, please try the following:

  1. Confirm that every part of your request URL is valid (HTTPS, etc).
    1. You generally will not need to update your headers.

Postman 1:

"status": "CLIENT_ERROR",
"message": "This operation has been blocked as a potential Cross-Site Request Forgery (CSRF). Please either specify a 'content-type' header (with a type that is not one of application/x-www-form-urlencoded, multipart/form-data, text/plain) or provide a non-empty value for one of the following headers: x-apollo-operation-name, apollo-require-preflight\n"

Confirm that previously defined variables are used in your query options.

Postman 1:

"status": "CLIENT_ERROR",
"message": "Variable \"$id\" is never used."

401/401

This error code's message may vary per application, cause, and effect. Please consider the following resolutions:

  1. Resend your query immediately in various ways if needed.
    1. In rare cases, please wait 24 hours for system refresh. This might happen around regular and irregular releases (HOOT-8646).
  2. Confirm your API Key is valid and being submitted properly.
  3. Confirm your API Key has at least 1 access group.
  4. Create and try a new API Key.

Postman 1:

Unauthorized
{
"status": 401,
"msg": "ERROR - Cannot return web token from key",
"data": null,
"actionTaker": {},
"tenantVariables": {},
"requestMethod": "POST",
"requestStatus": 401
}

Zapier 1:

The app returned "ERROR - Key not provided".
What happened (You are seeing this because you are an admin):
Stack trace:
ResponseError: {"status":401,"headers":{"content-type":"application/json; charset=utf-8","retry-after":null},"content":"{\"status\":401,\"msg\":\"ERROR - Key not provided\",\"data\":null,\"actionTaker\":{},\"tenantVariables\":{},\"requestMethod\":\"POST\",\"requestStatus\":401}","request":{"url":"https://apilabs.athennian.com?x-api-key=...redacted

404/404

To resolve, please confirm the following:

  1. Endpoint URL validity (Z-11358)

Postman 1:

NOT FOUND
<html>...<pre>Cannot POST /graphq</pre>l...</html>