API Return codes

Created by Cortney Roberson, Modified on Wed, 09 Nov 2022 at 04:31 PM by Cortney Roberson



The Gremlin Agent is unable to authenticate against the API. Causes of this error are usually due to bad or missing credentials files or certificates, or a revocation issued against the client.


  • 401 Unauthorized - Authorization header is missing or malformed
  • Client has been revoked (401 Unauthorized)
  • AUTH_RENEW: 401 Unauthorized


  • Ensure you have valid credentials (Certificates or API keys) in a location that Gremlin can read from.
  • Ensure Gremlin has proper read+write access to /var/lib/gremlin
  • Remove the file /var/lib/gremlin/.credentials if it exists
  • Rerun gremlin init

This error can also be the result of a race condition when Gremlin daemon is being started prior to the environment variables being exported.

In some specific cases, this error can also occur when multiple hosts or agents are configured with the same GREMLIN_IDENTIFIER. Common places this can occur:

  • Improperly configured ECS/Kubrenettes/Mesosphere where multiple Gremlin Agents are assigned the same virtual IP
  • Missing HOST meta data on AWS/GCP/Azure which causes Gremlin to revert to the default localhost Identifier


The client limit for your company or team has been reached, Gremlin does not have a license to apply to the client.

You may terminate or revoke existing clients, or contact Gremlin Sales to increase the client limit.


The account, most likely a trial account, has expired. Contact Gremlin Sales to extend the trial.


This is most often attributed to a host having bad time data. Verify the system clock of the host and try again. If this problem persists after validating your host's system clock, contact Gremlin Support.


An error code of 409 indicates there is a conflicting attack running on the host. This is most often seen in the case of one network attack running (for example, a blackhole attack) and attempting to launch a second network attack. However, this can also occur when trying to run two concurrent network or state attacks against the same target.

Was this article helpful?

That’s Great!

Thank you for your feedback

Sorry! We couldn't be helpful

Thank you for your feedback

Let us know how can we improve this article!

Select atleast one of the reasons

Feedback sent

We appreciate your effort and will try to fix the article