Errors

This page enumerates all errors that might be received while using the Turnkey API.

Turnkey Error

Since Turnkey's API is a remote procedure call (RPC) API -- Turnkey error codes (errors received starting with Turnkey error), correspond directly with GRPC error codes.

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/

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.

Action	GRPC Code	HTTP Code	Reason
Authentication	NotFound	404	no organization found with the given ID
Authentication	Internal	500	internal error
Authentication	Internal	500	failed to read organization parent ID
Authentication	Internal	500	failed to execute get sub-organization by credential ID query
Authentication	Internal	500	failed to execute get sub-organization by public key query
Authentication	Internal	500	cannot find user for public key
Authentication	InvalidArgument	400	malformed organization ID provided
Authentication	InvalidArgument	400	bad request body
Authentication	PermissionDenied	403	api operations disabled
Authentication	ResourceExhausted	403	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.
Authentication	ResourceExhausted	403	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.
Authentication	PermissionDenied	403	request not authorized
Authentication	Unauthenticated	401	no valid authentication signature found for request
Authentication	Unauthenticated	401	could not find public key in organization
Authentication	Unauthenticated	401	failed while looking up public key in parent organization
Authentication	Unauthenticated	401	could not find public key in organization or its parent organization
Authentication	Unauthenticated	401	could not verify WebAuthN signature
Authentication	Unauthenticated	401	credential ID could not be found in organization or its parent organization
Authentication	Unauthenticated	401	public key could not be found in organization or its parent organization
Authentication	Unauthenticated	401	more than one suborg associated with a credential ID
Authentication	Unauthenticated	401	more than one suborg associated with a public key
Authentication	Unauthenticated	401	cannot extract api key signature
Authentication	Unauthenticated	401	could not verify api key signature
Authentication	Unauthenticated	401	request does not have a valid authentication header
Authentication	Unauthenticated	401	expired api key
Authentication	Unauthenticated	401	malformed activity stamp
Authentication	Unauthenticated	401	could not extract webauthn stamp
Authentication	Unauthenticated	401	could not extract api key stamp
Authentication	Unauthenticated	401	cannot authenticate public API activity request without a stamp (X-Stamp/X-Stamp-Webauthn header)
Authentication	NotFound	404	webauthn authenticator not found in organization
Authentication	NotFound	404	webauthn authenticator not found in organization or parent organization
Authentication	Internal	500	failed to load webauthn authenticator
Signing	InvalidArgument	400	invalid payload encoding
Signing	InvalidArgument	400	invalid hash function
Signing	Internal	500*	transaction type not implemented
Email Auth	InvalidArgument	400	invalid magic link template
Email Auth	InvalidArgument	400	failed to get email template contents
Email Auth	InvalidArgument	400	failed to unmarshal template variables
Email Auth	Internal	500	error while sending auth email
Email Auth	Internal	500	failed to find user by email
List Users	PermissionDenied	403	authentication failed
List Users	InvalidArgument	400*	failed to load organizations
List Users	Internal	500	failed users lookup
Policies	InvalidArgument	400	policy label must be unique
Policies	InvalidArgument	400	invalid policy consensus
Policies	InvalidArgument	400	invalid policy condition
Update Root Quorum	InvalidArgument	400	quorum threshold must be non-zero integer
Update Root Quorum	InvalidArgument	400	quorum threshold cannot be less than quorum user count
Update Root Quorum	InvalidArgument	400	quorum users missing
Update Root Quorum	InvalidArgument	400	quorum missing
Create Sub Org	InvalidArgument	400	invalid api key expiration
Create Sub Org	InvalidArgument	400	missing parameter: user authenticator attestation
Create Sub Org	InvalidArgument	400	invalid authenticator attestation
Create Sub Org	InvalidArgument	400	missing parameter: user authenticator attestation auth data
Create Sub Org	ResourceExhausted	429	user has exceeded maximum authenticators
Create Sub Org	ResourceExhausted	429	user has exceeded maximum long-lived api keys
Create Sub Org	ResourceExhausted	429	user has exceeded maximum short-lived api keys
Create Sub Org	InvalidArgument	400	missing wallet params
Create Sub Org	InvalidArgument	400	invalid path format
Create Sub Org	InvalidArgument	400	invalid path
Create Sub Org	InvalidArgument	400	invalid address format
Create Sub Org	InvalidArgument	400	invalid curve
Create Sub Org	InvalidArgument	400	curve required
Approve Activity	NotFound	404	No activity found with fingerprint. Consensus activities must target an existing activity by fingerprint