Errors - Turnkey

An error returned by the Turnkey API might look something like this:

Turnkey error 3: organization mismatch: request is targeting organization ("USER SUB ORG"), but voters are in organization ("OUR MAIN ORG") (Details: [{"@type":"type.googleapis.com/errors.v1.TurnkeyErrorDetail","turnkeyErrorCode":"ORGANIZATION_MISMATCH"}])

Within this error message there are a few different parts that are worth breaking down. First the GRPC Error code:

Turnkey error 3:

This GRPC error wraps what we call a Turnkey Error which looks something like:

organization mismatch: request is targeting organization ("USER SUB ORG"), but voters are in organization ("OUR MAIN ORG")

And when available, a turnkeyErrorCode in the Details section:

(Details: [{"@type":"type.googleapis.com/errors.v1.TurnkeyErrorDetail","turnkeyErrorCode":"ORGANIZATION_MISMATCH"}])

Error Handling Best Practices

What matters most for error handling is the Turnkey Error: the human-readable message and turnkeyErrorCode (when available). You should not perform error handling based on the GRPC code - these are used internally and will eventually be removed. More on that here. Understanding TurnkeyErrorCodes: These codes represent categories of errors, not specific messages. For example, SIGNATURE_INVALID may appear with messages like “could not verify WebAuthn signature” or “could not verify api key signature”. Use the turnkeyErrorCode to identify the error category programmatically, and use the human-readable message for specific details.

Available TurnkeyErrorCodes

The following error codes may be returned in error details:

Code	Description
`UNSPECIFIED`	Error code not specified
`INTERNAL`	Internal server error
`ORGANIZATION_NOT_FOUND`	The specified organization could not be found
`API_OPERATIONS_DISABLED`	Global API access is temporarily disabled
`SIGNING_QUOTA_EXCEEDED`	Organization has exceeded its signing quota and cannot execute activities
`REQUEST_NOT_AUTHORIZED`	Request is not authorized - may occur when accessing resources outside permissions or beyond session restrictions
`PUBLIC_KEY_NOT_FOUND`	Public key could not be found in the organization or its parent
`RATE_LIMIT_EXCEEDED`	Organization has been rate limited and cannot execute activities
`SIGNATURE_MISSING`	Required authentication signature is missing from the request
`SIGNATURE_INVALID`	Could not verify API key or WebAuthn signature
`CREDENTIAL_NOT_FOUND`	Credential or WebAuthn authenticator not found in organization or its parent
`CREDENTIAL_CONFLICT`	Multiple sub-organizations are associated with this credential, creating ambiguous authentication
`API_KEY_EXPIRED`	The API key has expired and can no longer be used
`REQUEST_INVALID`	Request contains invalid or missing required parameters
`FORBIDDEN`	User does not have permission to view or access this organization
`UNAUTHENTICATED`	Authentication failed - request lacks valid authentication credentials
`UNSUPPORTED_TRANSACTION_TYPE`	Transaction type is not supported (supported: Ethereum, Solana, Tron, Bitcoin, Tempo)
`INVALID_TRANSACTION`	Transaction structure is invalid (e.g., too many addresses in Solana transaction)
`INVALID_OIDC_TOKEN`	OIDC token is invalid or missing required claims (aud, sub, iss)
`INVALID_ORGANIZATION_ID`	Organization ID is invalid or malformed (must be a valid UUID)
`OAUTH2_CREDENTIAL_NOT_FOUND`	The specified OAuth 2.0 credential could not be found
`OAUTH2_PROVIDER_NOT_FOUND`	The specified OAuth 2.0 provider could not be found
`INVALID_OAUTH2_PROVIDER`	OAuth 2.0 provider configuration is invalid or misconfigured
`OAUTH2_PROVIDER_NOT_CONFIGURED`	OAuth 2.0 provider has not been configured for this organization
`INVALID_ACTIVITY_CALLER`	This activity cannot be called by sub-organizations
`WALLET_ACCOUNT_NOT_EXPORTED`	Wallet account has not been exported and cannot be deleted without export
`INVALID_TIME`	Time range is invalid or results in excessive intervals
`RPC_CALL_ERROR`	RPC provider communication error
`INVALID_EMAIL`	Email address is invalid - check format, domain, and TLD (Top-Level Domain)
`INVALID_FQDN`	Email domain could not be reached or verified
`OAUTH_PROVIDER_ALREADY_EXISTS`	OAuth provider with same audience, subject, and issuer already exists
`EMAIL_SENDING_DISABLED`	Email sending functionality is currently disabled

Not all errors currently include a turnkeyErrorCode, though we aim to include one in all customer-facing errors. If you encounter an error where you would expect a turnkeyErrorCode but don’t see one, please contact Turnkey support.

Detailed Error Messages

The below table enumerates common errors across different actions that can be taken using the API. It contains GRPC codes, HTTP codes, and error messages. More on GRPC error codes below. Click on the message to view detailed explanation of possible causes and troubleshooting tips for that specific error.

GRPC Code	HTTP Code	Message
InvalidArgument	400	malformed organization ID provided
InvalidArgument	400	bad request body
InvalidArgument	400	failed to load organizations
InvalidArgument	400	policy label must be unique
InvalidArgument	400	invalid policy consensus
InvalidArgument	400	invalid policy condition
InvalidArgument	400	quorum threshold must be non-zero integer
InvalidArgument	400	quorum users missing
InvalidArgument	400	invalid api key expiration
InvalidArgument	400	missing parameter: user authenticator attestation
InvalidArgument	400	invalid authenticator attestation
InvalidArgument	400	missing parameter: user authenticator attestation auth data
InvalidArgument	400	missing wallet params
InvalidArgument	400	invalid path format
InvalidArgument	400	invalid path
InvalidArgument	400	invalid address format
InvalidArgument	400	invalid curve
InvalidArgument	400	curve required
InvalidArgument	400	invalid payload encoding
InvalidArgument	400	invalid hash function
InvalidArgument	400	invalid magic link template
InvalidArgument	400	failed to get email template contents
InvalidArgument	400	failed to unmarshal template variables
InvalidArgument	400	organization mismatch
InvalidArgument	400	invalid wallet account UUID
InvalidArgument	400	wallet account not part of your organization
InvalidArgument	400	wallet account has not been exported
InvalidArgument	400	invalid OIDC token
InvalidArgument	400	invalid email address
InvalidArgument	400	could not reach email
InvalidArgument	400	auth_code must be set
InvalidArgument	400	code_verifier must be set
InvalidArgument	400	oauth2_credential_id must be set
InvalidArgument	400	redirect_uri must be set
InvalidArgument	400	client_id must be set
Unauthenticated	401	no valid authentication signature found for request
Unauthenticated	401	could not find public key in organization
Unauthenticated	401	failed while looking up public key in parent organization
Unauthenticated	401	could not find public key in organization or its parent organization
Unauthenticated	401	could not verify WebAuthN signature
Unauthenticated	401	credential ID could not be found in organization or its parent organization
Unauthenticated	401	public key could not be found in organization or its parent organization
Unauthenticated	401	more than one suborg associated with a credential ID
Unauthenticated	401	more than one suborg associated with a public key
Unauthenticated	401	could not verify api key signature
Unauthenticated	401	expired api key
Unauthenticated	401	malformed activity stamp
Unauthenticated	401	could not extract webauthn stamp
Unauthenticated	401	could not extract api key stamp
Unauthenticated	401	cannot authenticate public API activity request without a stamp (X-Stamp/X-Stamp-Webauthn header)
PermissionDenied	403	request not authorized
PermissionDenied	403	api operations disabled
PermissionDenied	403	authentication failed
NotFound	404	webauthn authenticator not found in organization
NotFound	404	webauthn authenticator not found in organization or parent organization
NotFound	404	no organization found with the given ID
NotFound	404	No activity found with fingerprint. Consensus activities must target an existing activity by fingerprint
ResourceExhausted	429	user has exceeded maximum authenticators
ResourceExhausted	429	user has exceeded maximum long-lived api keys
ResourceExhausted	429	user has exceeded maximum short-lived api keys
ResourceExhausted	429	this organization cannot execute activities because it is over its allotted quota. Please reach out to the Turnkey team (help@turnkey.com) for more information.
ResourceExhausted	429	this sub-organization cannot execute activities because its parent is over its allotted quota. Please reach out to the Turnkey team (help@turnkey.com) for more information.
ResourceExhausted	429	this organization cannot execute activities because it has been rate limited. Please reach out to the Turnkey team (help@turnkey.com) for more information.
ResourceExhausted	429	this sub-organization cannot execute activities because its parent has been rate limited. Please reach out to the Turnkey team (help@turnkey.com) for more information.
Internal	500	internal server error

GRPC Error Codes

Turnkey uses GRPC internally to communicate with our internal services whenever an API request is made. Due to this some errors will be wrapped with GRPC error messages. These error codes are listed below for your convenience, however these will not remain in Turnkey error messages forever and you should not do error handling based on these codes as these could be removed at any time. In the following example Turnkey error 3: represents a grpc error (error code 3, INVALID_ARGUMENT) wrapping a Turnkey error. Example

Turnkey error 3: organization mismatch: request is targeting organization ("USER SUB ORG"), but voters are in organization ("OUR MAIN ORG")

GRPC Status Codes Reference

Code	Number	Description
OK	0	Not an error; returned on success.
CANCELLED	1	The operation was cancelled, typically by the caller.
UNKNOWN	2	Unknown error. For example, this error may be returned when a `Status` value received from another address space belongs to an error space that is not known in this address space. Also errors raised by APIs that do not return enough error information may be converted to this error.
INVALID_ARGUMENT	3	The client specified an invalid argument. Note that this differs from `FAILED_PRECONDITION`. `INVALID_ARGUMENT` indicates arguments that are problematic regardless of the state of the system (e.g., a malformed file name).
DEADLINE_EXCEEDED	4	The deadline expired before the operation could complete. For operations that change the state of the system, this error may be returned even if the operation has completed successfully. For example, a successful response from a server could have been delayed long
NOT_FOUND	5	Some requested entity (e.g., file or directory) was not found. Note to server developers: if a request is denied for an entire class of users, such as gradual feature rollout or undocumented allowlist, `NOT_FOUND` may be used. If a request is denied for some users within a class of users, such as user-based access control, `PERMISSION_DENIED` must be used.
ALREADY_EXISTS	6	The entity that a client attempted to create (e.g., file or directory) already exists.
PERMISSION_DENIED	7	The caller does not have permission to execute the specified operation. `PERMISSION_DENIED` must not be used for rejections caused by exhausting some resource (use `RESOURCE_EXHAUSTED` instead for those errors). `PERMISSION_DENIED` must not be used if the caller can not be identified (use `UNAUTHENTICATED` instead for those errors). This error code does not imply the request is valid or the requested entity exists or satisfies other pre-conditions.
RESOURCE_EXHAUSTED	8	Some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space.
FAILED_PRECONDITION	9	The operation was rejected because the system is not in a state required for the operation’s execution. For example, the directory to be deleted is non-empty, an rmdir operation is applied to a non-directory, etc. Service implementors can use the following guidelines to decide between `FAILED_PRECONDITION`, `ABORTED`, and `UNAVAILABLE`: (a) Use `UNAVAILABLE` if the client can retry just the failing call. (b) Use `ABORTED` if the client should retry at a higher level (e.g., when a client-specified test-and-set fails, indicating the client should restart a read-modify-write sequence). (c) Use `FAILED_PRECONDITION` if the client should not retry until the system state has been explicitly fixed. E.g., if an “rmdir” fails because the directory is non-empty, `FAILED_PRECONDITION` should be returned since the client should not retry unless the files are deleted from the directory.
ABORTED	10	The operation was aborted, typically due to a concurrency issue such as a sequencer check failure or transaction abort. See the guidelines above for deciding between `FAILED_PRECONDITION`, `ABORTED`, and `UNAVAILABLE`.
OUT_OF_RANGE	11	The operation was attempted past the valid range. E.g., seeking or reading past end-of-file. Unlike `INVALID_ARGUMENT`, this error indicates a problem that may be fixed if the system state changes. For example, a 32-bit file system will generate `INVALID_ARGUMENT` if asked to read at an offset that is not in the range [0,2^32-1], but it will generate `OUT_OF_RANGE` if asked to read from an offset past the current file size. There is a fair bit of overlap between `FAILED_PRECONDITION` and `OUT_OF_RANGE`. We recommend using `OUT_OF_RANGE` (the more specific error) when it applies so that callers who are iterating through a space can easily look for an `OUT_OF_RANGE` error to detect when they are done.
UNIMPLEMENTED	12	The operation is not implemented or is not supported/enabled in this service.
INTERNAL	13	Internal errors. This means that some invariants expected by the underlying system have been broken. This error code is reserved for serious errors.
UNAVAILABLE	14	The service is currently unavailable. This is most likely a transient condition, which can be corrected by retrying with a backoff. Note that it is not always safe to retry non-idempotent operations.
DATA_LOSS	15	Unrecoverable data loss or corruption.
UNAUTHENTICATED	16	The request does not have valid authentication credentials for the operation.

Source: https://grpc.io/docs/guides/status-codes/

Troubleshooting

no organization found with the given ID

Common causes:

An unknown organization ID was passed in a request made to the Turnkey API

Troubleshooting tips:

Confirm that you are using the proper Organization ID. All Turnkey resources are identified with a UUID, so confirm you are not passing a different resource’s UUID as the organization ID in your request.

malformed organization ID provided

Common causes:

An improperly formatted organization ID UUID was passed in a request made to the Turnkey API

Troubleshooting tips:

Confirm the the UUID conforms to the UUID standard XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

bad request body

Common causes:

A malformed request body was passed in a request made to the Turnky API

Troubleshooting tips:

A typical activity request has the type, timestampMS, and organizationId parameters at the top level and then a parameters parameter with more specific parameters based on the request type. For example a CREATE_WALLET activity request body might look something like this:

{
  "type": "ACTIVITY_TYPE_CREATE_WALLET",
  "timestampMs": "<string>",
  "organizationId": "string",
  "parameters": {
    "walletName": "string",
    "accounts": [
      {
        "curve": "CURVE_SECP256K1",
        "pathFormat": "PATH_FORMAT_BIP32",
        "path": "string",
        "addressFormat": "ADDRESS_FORMAT_UNCOMPRESSED"
      }
    ],
    "mnemonicLength": 0
  }
}

A get resource request body might look slightly different with less fields. An example of a GET_WALLET request body looks something like this:

{
  "organizationId": "string",
  "walletId": "string"
}

api operations disabled

Common causes:

Turnkey has disabled API operations globally.

Troubleshooting tips:

This situation will only happen in the most extreme case and should not be something you need to worry about.

this organization cannot execute activities because it is over its allotted quota. Please reach out to the Turnkey team (help@turnkey.com) for more information.

Common causes:

You have exceeded your monthly signing quota. The first 25 signatures a month are free for “free” users.
You have reached a resource limit on a particular resource. You can find out about our resource limits here.

Troubleshooting tips:

If you need to increase your signature limit take a look at our pricing page and contact us at help@turnkey.com!
Resource limits are imposed globally and cannot be increased, speak with our team at help@turnkey.com to understand how to better integrate Turnkey with your system to utilize Turnkey to its highest potential.

this sub-organization cannot execute activities because its parent is over its allotted quota. Please reach out to the Turnkey team (help@turnkey.com) for more information.

Common causes:

You have exceeded your monthly signing quota. The first 25 signatures a month are free for “free” users.
You have reached a resource limit on a particular resource. You can find out about our resource limits here.

Troubleshooting tips:

If you need to increase your signature limit take a look at our pricing page and contact us at help@turnkey.com!
Resource limits are imposed globally and cannot be increased, speak with our team at help@turnkey.com to understand how to better integrate Turnkey with your system to utilize Turnkey to its highest potential.

this organization cannot execute activities because it has been rate limited. Please reach out to the Turnkey team (help@turnkey.com) for more information.

Common causes:

You have exceeded your rate limit. We need to maintain a per-customer rate limit to ensure that the service we provide to all of our customers service can be exceptional.

Troubleshooting tips:

If you are interested in increasing your rate limit reach out to us at help@turnkey.com!

this sub-organization cannot execute activities because its parent has been rate limited. Please reach out to the Turnkey team (help@turnkey.com) for more information.

Common causes:

You have exceeded your rate limit. We need to maintain a per-customer rate limit to ensure that the service we provide to all of our customers service can be exceptional.

Troubleshooting tips:

If you are interested in increasing your rate limit reach out to us at help@turnkey.com!

request not authorized

Common causes:

A user that created a request is not allowed to complete the action that was requested.
For example a parent-organization trying to create a wallet within a sub-organization that does not have a delegated access API key.

Troubleshooting tips:

Confirm that you are using the correct credentials for the request you are making.
Confirm that all necessary policies are in place so that the action that is requested can be performed.

no valid authentication signature found for request

Common causes:

No signature, or stamp, is attached to a request. All requests made to Turnkey’s api must be stamped so that Turnkey can authenticate and authorize the user who performed the request.

Troubleshooting tips:

Take a look at the page on stamps to get some information about stamps, what they are, and how they are created.
At a base level our SDK’s abstract away the complicated stamping process for you. Here are some example projects with our JS/TS SDK to get you started!

could not find public key in organization

Common causes:

The public key corresponding to the signature in a stamp is not found in the organization the request is targeting. This means that a request was formatted properly, but the authenticator used to create the request is not associated with the organization that the request was made for.

Troubleshooting tips:

Ensure that you have added the proper authenticators to the organization you are targeting.
Ensure that you are targeting the proper organization.

failed while looking up public key in parent organization

Common causes:

The public key corresponding to the signature in a stamp is not found in the organization the request is targeting. This means that a request was formatted properly, but the authenticator used to create the request is not associated with the organization that the request was made for.

Troubleshooting tips:

Ensure that you have added the proper authenticators to the organization you are targeting.
Ensure that you are targeting the proper organization.

could not find public key in organization or its parent organization

Common causes:

The public key corresponding to the signature in a stamp is not found in the organization the request is targeting. This means that a request was formatted properly, but the authenticator used to create the request is not associated with the organization that the request was made for.

Troubleshooting tips:

Ensure that you have added the proper authenticators to the organization you are targeting.
Ensure that you are targeting the proper organization.

could not verify WebAuthN signature

Common causes:

The signature used to create a stamp for a request cannot be verified for the organization the request is targeting. Again this means the request is formatted properly, but the authenticator used to create the request is not associated with the organization that the request was made for.

Troubleshooting tips:

Ensure that you have added the proper authenticators to the organization you are targeting.
Ensure that you are targeting the proper organization.

credential ID could not be found in organization or its parent organization

Common causes:

Turnkey cannot translate a public key obtained from a stamp that was created with a WebAuthn authenticator to a parent organization or one of its corresponding sub-organizations that the request was made for.

Troubleshooting tips:

Ensure that you have added the proper authenticators to the organization you are targeting.
Ensure that you are targeting the proper organization.

public key could not be found in organization or its parent organization

Common causes:

Turnkey cannot translate a public key obtained from a stamp to a parent organization or one of its corresponding sub-organizations that the request was made for.

Troubleshooting tips:

Ensure that you have added the proper authenticators to the organization you are targeting.
Ensure that you are targeting the proper organization.

more than one suborg associated with a credential ID

Common causes:

This error occurs for requests like whoami. In particular this request tries to go backwards from the stamp to the public key then to a corresponding sub-orgnaization under a parent organization. If there are multiple sub-organizations with the same public key corresponding to an authenticator it is unknown who is initiating that particular request without more context.

Troubleshooting tips:

Inlcude the sub-organization ID in the whoami request body.
Avoid including the same authenticator in multiple sub-organizations

more than one suborg associated with a public key

Common causes:

This error occurs for requests like whoami. In particular this request tries to go backwards from the stamp to the public key then to a corresponding sub-orgnaization under a parent organization. If there are multiple sub-organizations with the same public key it is unknown who is initiating that particular request without more context.

Troubleshooting tips:

Inlcude the sub-organization ID in the whoami request body.
Avoid including the same authenticator in multiple sub-organizations

could not verify api key signature

Common causes:

The signature used to create a stamp for a request cannot be verified for the organization the request is targeting. This means the request is formatted properly, but the api-key used to create the request is not associated with the organization that the request was made for.

Troubleshooting tips:

Ensure that you have added the proper api-keys to the organization you are targeting.
Ensure that you are targeting the proper organization.

expired api key

Common causes:

The API key used for the request has expired

Troubleshooting tips:

Create a new API key to use for the request
Create an API key that doesn’t expire

malformed activity stamp

Common causes:

The stamp attached to a request is not formatted properly.

Troubleshooting tips:

Take a look at the page on stamps to get some information about stamps, what they are, and how they are created.
At a base level our SDK’s abstract away the complicated stamping process for you. Here are some example projects with our JS/TS SDK to get you started!

could not extract webauthn stamp

Common causes:

A stamp is not attached to a request.

Troubleshooting tips:

Take a look at the page on stamps to get some information about stamps, what they are, and how they are created.
At a base level our SDK’s abstract away the complicated stamping process for you. Here are some example projects with our JS/TS SDK to get you started!

could not extract api key stamp

Common causes:

A stamp is not attached to a request.

Troubleshooting tips:

Take a look at the page on stamps to get some information about stamps, what they are, and how they are created.
At a base level our SDK’s abstract away the complicated stamping process for you. Here are some example projects with our JS/TS SDK to get you started!

cannot authenticate public API activity request without a stamp (X-Stamp/X-Stamp-Webauthn header)

Common causes:

A stamp is not attached to a request.

Troubleshooting tips:

Take a look at the page on stamps to get some information about stamps, what they are, and how they are created.
At a base level our SDK’s abstract away the complicated stamping process for you. Here are some example projects with our JS/TS SDK to get you started!

webauthn authenticator not found in organization

Common causes:

The signature used to create a stamp for a request cannot be verified for the organization the request is targeting. This means the request is formatted properly, but the webauthn authenticator used to create the request is not associated with the organization that the request was made for.

Troubleshooting tips:

Ensure that you have added the proper authenticator to the organization you are targeting.
Ensure that you are targeting the proper organization.

webauthn authenticator not found in organization or parent organization

Common causes:

The signature used to create a stamp for a request cannot be verified for the organization the request is targeting. This means the request is formatted properly, but the webauthn authenticator used to create the request is not associated with the organization that the request was made for.

Troubleshooting tips:

Ensure that you have added the proper authenticator to the organization you are targeting.
Ensure that you are targeting the proper organization.

invalid payload encoding

Common causes:

This error is specific to the sign_raw_payload endpoint. A valid encoding needs to be passed so that Turnkey can properly sign the requested message.

Troubleshooting tips:

Use a valid encoding scheme from the following: PAYLOAD_ENCODING_HEXADECIMAL, PAYLOAD_ENCODING_TEXT_UTF8

invalid hash function

Common causes:

This error is specific to the sign_raw_payload endpoint. A valid hash function needs to be passed so that Turnkey can properly hash and sign the requested message.

Troubleshooting tips:

Use a valid hash function scheme from the following: HASH_FUNCTION_NO_OP, HASH_FUNCTION_SHA256, HASH_FUNCTION_KECCAK256, HASH_FUNCTION_NOT_APPLICABLE
More information about HASH_FUNCTION_NO_OP here
More information about HASH_FUNCTION_NOT_APPLICABLE here

invalid magic link template

Common causes:

The email template provided for specific activities is invalid.

Troubleshooting tips:

Read more about bespoke email templates
Reach out to Turnkey at help@turnkey.com!

failed to get email template contents

Common causes:

There was an error getting the email template for an associated activity

Troubleshooting tips:

Reach out to Turnkey at help@turnkey.com!

failed to unmarshal template variables

Common causes:

There are invalid template variables used in your email template.

Troubleshooting tips:

Read more about bespoke email templates
Reach out to Turnkey at help@turnkey.com!

authentication failed

Common causes:

Turnkey was unable to authenticate the user based on the stamp provided.

Troubleshooting tips:

Ensure that all proper authenticators and api-keys have been added to the organization.
Read more about how to create a stamp for a request here

failed to load organizations

Common causes:

A request is targeting an unknown organization ID.

Troubleshooting tips:

Ensure that the passed organization ID in the request is valid.

policy label must be unique

Common causes:

A new policy that is to be created shares the same name as a different policy. Policy names must be unique, and names in general must be unique per resource, so that they can be properly identified.

Troubleshooting tips:

Change the label/name that will be used for the new policy.
Delete the old policy.
Update the old policy to have a new name.

invalid policy consensus

Common causes:

An invalid consensus expression is passed.

Troubleshooting tips:

Read more about policy structure here

invalid policy condition

Common causes:

An invalid condition expression is passed.

Troubleshooting tips:

Read more about policy structure here

quorum threshold must be non-zero integer

Common causes:

Quorum is the required amount of approvals by root quorum members needed for an action to take place within an organization.

Troubleshooting tips:

When creating a sub-organization or updating the root quroum amount, use a non-zero positive integer.

quorum users missing

Common causes:

A user marked as part of the root quorum is missing from the set of users within an organization. This is a validation error that can occur when trying to delete a user that is part of the root quorum.

Troubleshooting tips:

Before deleting the user, remove them from the root quroum using Update Root Quorum

invalid api key expiration

Common causes:

An invalid expiration time was passed in for an api key’s expiration time parameter when using Create API Key

Troubleshooting tips:

The expirationSeconds parameter is passed as string of seconds of how long the key should last. Any non-positive non-integer string will be considered invalid.

missing parameter: user authenticator attestation

Common causes:

An attestation parameter is not passed when performing a request regarding an authenticator. For example Create Authenticators

Troubleshooting tips:

The attestation generated by the authenticator includes a new key pair, the challenge, and device metadata that is signed, read more about attestations here.
An example of getting the correct parameters needed to use the Create Authenticators endpoint can be found within our react-components SDK example

invalid authenticator attestation

Common causes:

An attestation parameter is not valid when performing a request regarding an authenticator. For example Create Authenticators

Troubleshooting tips:

The attestation generated by the authenticator includes a new key pair, the challenge, and device metadata that is signed, read more about attestations here.
An example of getting the correct parameters needed to use the Create Authenticators endpoint can be found within our react-components SDK example

missing parameter: user authenticator attestation auth data

Common causes:

The attestation auth data parameter is not valid when performing a request regarding an authenticator. For example Create Authenticators. This parameter is obtained as part of the attestation object.

Troubleshooting tips:

An example of getting the correct parameters needed to use the Create Authenticators endpoint can be found within our react-components SDK example

user has exceeded maximum authenticators

Common causes:

Turnkey allows up to 10 authenticators per user. This is a hard resource limit. More information on resource limits here.

Troubleshooting Tips:

Delete any unnecessary authenticators attached to a user.
Create a new user within the same organization and attach the authenicator to that user.

user has exceeded maximum long-lived api keys

Common causes:

Turnkey allows up to 10 long-lived api keys per user. This is a hard resource limit. More information on resource limits here.

Troubleshooting Tips:

Delete any unnecessary long-lived API keys attached to a user.
Create a new user within the same organization and attach the API key to that user.

user has exceeded maximum short-lived api keys

Common causes:

Turnkey allows up to 10 short-lived api keys per user. This is a hard resource limit. More information on resource limits here. Short-lived API keys will automatically be deleted from an organization when they are expired.

Troubleshooting Tips:

Delete any unnecessary short-lived API keys attached to a user.
Create a new user within the same organization and attach the API key to that user.

missing wallet params

Common causes:

Some wallet/wallet account parameters have been omitted when creating a sub-organization

Troubleshooting tips:

Include all of the required parameters when creating a wallet during sub-organization creation. More info on the parameters here.

invalid path format

Common causes:

This error occurs when an invalid path format parameter is passed to a request like Create Wallet Accounts.

Troubleshooting tips:

For now the path format must be: PATH_FORMAT_BIP32.

invalid path

Common causes:

An invalid path parameter is passed to a request like Create Wallet Accounts. Paths cannot be reused within the same HD wallet.

Troubleshooting tips:

The path is a string that is used to derive a new account within an HD wallet. A list of default paths per address format can be found here
Paths cannot be reused within the same HD wallet.

invalid address format

Common causes:

An invalid address format parameter is passed to a request like Create Wallet Accounts.

Troubleshooting tips:

Turnkey offers a wide range of support for many ecosystems. A list of valid address formats can be found in the table here.
More about Turnkey and general ecosystem support can be found here.

invalid curve

Common causes:

An invalid curve parameter is passed to a request like Create Wallet Accounts.

Troubleshooting tips:

Before ecosystem level integrations Turnkey offers support on a curve level. This makes us extendable to any ecosystem that is based on a curve we support. A list of valid curve parameters can be found in the table here.
More about Turnkey and general ecosystem support can be found here.

curve required

Common causes:

The curve parameter is not passed to a request like Create Wallet Accounts.

Troubleshooting tips:

Before ecosystem level integrations Turnkey offers support on a curve level. This makes us extendable to any ecosystem that is based on a curve we support. A list of valid curve parameters can be found in the table here.
More about Turnkey and general ecosystem support can be found here.

failed to parse transaction

Common causes:

The unsignedTransaction payload cannot be decoded by the policy engine, it might have not been serlialized properly.

Troubleshooting tips:

Try to decode the payload independently and see if it returns the expected result.
We’ve noticed that for EIP1559 transaction types, the go-ethereum MarshalBinary() function will include the R, S, V values which should not be present within the serialized payload. Try to reconstruct the RLP payload manually without the R, S, V values, see the example below:

main.go

package main

import (
"encoding/hex"
"fmt"
"log"
"math/big"

"github.com/ethereum/go-ethereum/common"
"github.com/ethereum/go-ethereum/core/types"
"github.com/ethereum/go-ethereum/rlp"
)

func main() {
to := common.HexToAddress("0x...")

txData := &types.DynamicFeeTx{
	ChainID:    big.NewInt(1),
	Nonce:      0,
	GasTipCap:  big.NewInt(12344),
	GasFeeCap:  big.NewInt(10010000000),
	Gas:        100000,
	To:         &to,
	Value:      big.NewInt(1),
	Data:       hexDecode("<tx_data>"),
	AccessList: types.AccessList{}, // Optional
}

// RLP-encode only the fields included in the unsigned tx
unsignedRLP := encodeUnsignedDynamicFeeTx(txData)

// Prepend EIP-1559 type byte (0x02)
serializedUnsigned := append([]byte{types.DynamicFeeTxType}, unsignedRLP...)

fmt.Printf("Unsigned serialized tx: 0x%x\n", serializedUnsigned)

}

func encodeUnsignedDynamicFeeTx(tx *types.DynamicFeeTx) []byte {
rlpInput := []interface{}{
	tx.ChainID,
	tx.Nonce,
	tx.GasTipCap,
	tx.GasFeeCap,
	tx.Gas,
	tx.To,
	tx.Value,
	tx.Data,
	tx.AccessList,
}
out, err := rlp.EncodeToBytes(rlpInput)
if err != nil {
	log.Fatalf("failed to encode RLP: %v", err)
}
return out
}

func hexDecode(input string) []byte {
b, err := hex.DecodeString(input)
if err != nil {
	log.Fatal(err)
}
return b
}

No activity found with fingerprint. Consensus activities must target an existing activity by fingerprint

Common causes:

This error occurs during the Approve/Reject Activity activity. The fingerprint parameter must be a fingerprint of a valid activity.

Troubleshooting tips:

Confirm that a valid fingerprint of an activity that requires approval or rejection is passed as part of this activity.

internal server error

Common causes:

This error is thrown for a variety of internal server errors that are not due to user error. These activities will have an error id passed with them like: internal server error (9fbfda54-7141-4192-ae72-8bac3512149a) that can be used for troubleshooting.

Troubleshooting tips:

Retry the activity. This could be a fluke case and the following activity could pass without failure.
If you think there is problem or if your service is degraded, please reach out to Turnkey help@turnkey.com and provide the error id in the error message.

organization mismatch

Common causes:

The request is targeting one organization (e.g., a sub-organization), but the users signing/approving the request belong to a different organization (e.g., the parent organization)

Troubleshooting tips:

Ensure the organizationId in your request matches the organization where your signing users are located

invalid wallet account UUID

Common causes:

A malformed or invalid UUID was provided for a wallet account ID

Troubleshooting tips:

Verify the wallet account ID is a valid UUID in the format XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

wallet account not part of your organization

Common causes:

Attempting to delete or modify a wallet account that belongs to a different organization
Using a wallet account ID from another organization

Troubleshooting tips:

Verify the wallet account ID belongs to your organization
Check that you’re using the correct organization ID in your request

wallet account has not been exported

Common causes:

Attempting to delete a wallet account that has not been exported
The deleteWithoutExport parameter is not set to true when trying to delete an unexported wallet account

Troubleshooting tips:

Export the wallet account before deleting it using the export wallet account activity
Set deleteWithoutExport to true in your delete request if you want to delete without exporting (use with caution)

invalid OIDC token

Common causes:

The OIDC token format is invalid (not a valid JWT with 3 parts)
Required claims are missing from the OIDC token (aud, sub, or iss)
The token structure doesn’t match the expected format

Troubleshooting tips:

Verify the OIDC token is a valid JWT with three parts separated by periods (header.payload.signature)
Ensure the token includes all required claims:
- aud (audience): The intended recipient of the token
- sub (subject): The user identifier
- iss (issuer): The identity provider that issued the token
Check that your OIDC provider is correctly configured to include these claims

invalid email address

Common causes:

Email address format is invalid

Troubleshooting tips:

Verify the email address follows the standard format: user@domain.com
Remove any extra spaces or invalid characters from the email address

could not reach email

Common causes:

The email domain cannot be reached or verified
Invalid MX (Mail Exchange) records for the email domain
The email provider’s servers are unreachable or non-existent
The domain doesn’t have proper DNS configuration

Troubleshooting tips:

Verify the email domain is a valid, active domain
Check that the email provider’s MX records are properly configured
Try using an email address from a well-known provider (Gmail, Outlook, etc.) to test
If you believe this is in error, please contact Turnkey

Get started

Products

Crypto ecosystems

Developers

​Error Handling Best Practices

​Available TurnkeyErrorCodes

​Detailed Error Messages

​GRPC Error Codes

​GRPC Status Codes Reference

​Troubleshooting

​no organization found with the given ID

​malformed organization ID provided

​bad request body

​api operations disabled

​this organization cannot execute activities because it is over its allotted quota. Please reach out to the Turnkey team (help@turnkey.com) for more information.

​this sub-organization cannot execute activities because its parent is over its allotted quota. Please reach out to the Turnkey team (help@turnkey.com) for more information.

​this organization cannot execute activities because it has been rate limited. Please reach out to the Turnkey team (help@turnkey.com) for more information.

​this sub-organization cannot execute activities because its parent has been rate limited. Please reach out to the Turnkey team (help@turnkey.com) for more information.

​request not authorized

​no valid authentication signature found for request

​could not find public key in organization

​failed while looking up public key in parent organization

​could not find public key in organization or its parent organization

​could not verify WebAuthN signature

​credential ID could not be found in organization or its parent organization

​public key could not be found in organization or its parent organization

​more than one suborg associated with a credential ID

​more than one suborg associated with a public key

​could not verify api key signature

​expired api key

​malformed activity stamp

​could not extract webauthn stamp

​could not extract api key stamp

​cannot authenticate public API activity request without a stamp (X-Stamp/X-Stamp-Webauthn header)

​webauthn authenticator not found in organization

​webauthn authenticator not found in organization or parent organization

​invalid payload encoding

​invalid hash function

​invalid magic link template

​failed to get email template contents

​failed to unmarshal template variables

​authentication failed

​failed to load organizations

​policy label must be unique

​invalid policy consensus

​invalid policy condition

​quorum threshold must be non-zero integer

​quorum users missing

​invalid api key expiration

​missing parameter: user authenticator attestation

​invalid authenticator attestation

​missing parameter: user authenticator attestation auth data

​user has exceeded maximum authenticators

​user has exceeded maximum long-lived api keys

​user has exceeded maximum short-lived api keys

​missing wallet params

​invalid path format

​invalid path

​invalid address format

​invalid curve

​curve required

​failed to parse transaction

​No activity found with fingerprint. Consensus activities must target an existing activity by fingerprint

​internal server error

​organization mismatch

​invalid wallet account UUID

​wallet account not part of your organization

​wallet account has not been exported

​invalid OIDC token

​invalid email address

​could not reach email

Error Handling Best Practices

Available TurnkeyErrorCodes

Detailed Error Messages

GRPC Error Codes

GRPC Status Codes Reference

Troubleshooting

no organization found with the given ID

malformed organization ID provided

bad request body

api operations disabled

this organization cannot execute activities because it is over its allotted quota. Please reach out to the Turnkey team (help@turnkey.com) for more information.

this sub-organization cannot execute activities because its parent is over its allotted quota. Please reach out to the Turnkey team (help@turnkey.com) for more information.

this organization cannot execute activities because it has been rate limited. Please reach out to the Turnkey team (help@turnkey.com) for more information.

this sub-organization cannot execute activities because its parent has been rate limited. Please reach out to the Turnkey team (help@turnkey.com) for more information.

request not authorized

no valid authentication signature found for request

could not find public key in organization

failed while looking up public key in parent organization

could not find public key in organization or its parent organization

could not verify WebAuthN signature

credential ID could not be found in organization or its parent organization

public key could not be found in organization or its parent organization

more than one suborg associated with a credential ID

more than one suborg associated with a public key

could not verify api key signature

expired api key

malformed activity stamp

could not extract webauthn stamp

could not extract api key stamp

cannot authenticate public API activity request without a stamp (X-Stamp/X-Stamp-Webauthn header)

webauthn authenticator not found in organization

webauthn authenticator not found in organization or parent organization

invalid payload encoding

invalid hash function

invalid magic link template

failed to get email template contents

failed to unmarshal template variables

authentication failed

failed to load organizations

policy label must be unique

invalid policy consensus

invalid policy condition

quorum threshold must be non-zero integer

quorum users missing

invalid api key expiration

missing parameter: user authenticator attestation

invalid authenticator attestation

missing parameter: user authenticator attestation auth data

user has exceeded maximum authenticators

user has exceeded maximum long-lived api keys

user has exceeded maximum short-lived api keys

missing wallet params

invalid path format

invalid path

invalid address format

invalid curve

curve required

failed to parse transaction

No activity found with fingerprint. Consensus activities must target an existing activity by fingerprint

internal server error

organization mismatch

invalid wallet account UUID

wallet account not part of your organization

wallet account has not been exported

invalid OIDC token

invalid email address

could not reach email