Errors
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")
Within this error message there are a few different parts that are worth breaking down. First the GRPC Error code. This looks like this:
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")
What is more important to you as a developer is the TurnkeyError. This will give you information about what error occured and how you can handle it. In fact, you should not perform error handling based on the GRPC code. These codes are meant to be used internally and will eventually be removed from our error responses. More on that here. This page enumerates all errors that might be received while using the Turnkey API and also provides information about causes for these errors and helpful troubleshooting tips.
All Error Codes for Actions
The below table enumerates all errors across different actions that can be taken using the API. It contains both the GRPC codes as well as the HTTP codes corresponding with each error as well as the displayed error message. More on GRPC error codes below this table. Click on the message to view a details explanation of possible causes and trouble shooting tips for that specific 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, andorganizationIdparameters at the top level and then aparametersparameter 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 inforamtion 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 inforamtion 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 inforamtion 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 inforamtion 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 inforamtion 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_OPhere - More information about
HASH_FUNCTION_NOT_APPLICABLEhere
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
expirationSecondsparameter 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 unecessary 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 unecessary 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 unecessary 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 integrtaions 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.
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.