These docs are for v2.0. Click to read the latest docs for v3.0.

A list of possible errors returned by Hook APIs.

Return code design

Web assembly allows for exceptions (traps) however this language feature is not used for Hooks. Instead there is only one way to return from any Hook API (you may think of every Hook API as being noexcept).

To provide for efficient error handling:

  1. All Hook API functions return a signed integer.
  2. All negative return codes are an error.
  3. All return codes 0 or greater are a function specific output, usually but not always the number of bytes read or written.

Error codes

Error codes are global across all Hook APIs and may be found in the table below.

NameValueDescription
SUCCESS>= 0Non-negative return codes refer always to success and usually indicate the number of bytes written or events performed, depending on the specific API.
OUT_OF_BOUNDS-1A pointer or buffer length provided as a parameter described memory outside of the Hook's allowed memory region.
INTERNAL_ERROR-2Reserved for internal invariant trips, generally unrelated to inputs. These should be reported with an issue.
TOO_BIG-3Attempted to set a parameter or value larger than the allowed space.
TOO_SMALL-4The API was unable to produce output to the write_ptr because the specified write_len was too small.
DOESNT_EXIST-5The requested object or item wasn't found.
NO_FREE_SLOTS-6The Hook attempted to allocate an item into a slot, but there were no slots free. To avoid ensure re-use of existing slots. The maximum number of slots is 255.
INVALID_ARGUMENT-7One or more of the parameters to the API were invalid according to the individual API's specification.
ALREADY_SET-8Some APIs allow for a once-per-execution parameter to be set. A second attempt to set a once-per-execution parameter results in this error.
PREREQUISITE_NOT_MET-9An API required the Hook to do something before the API is allowed to be called. Check the API's documentation.
FEE_TOO_LARGE-10During fee calculation if an absurdly large fee is calculated this error is returned.
EMISSION_FAILURE-11An attempt to emit() a TXN was unsccessful for any of a number of reasons. Check the trace log of the rippled to which you are submitting the originating TXN.
TOO_MANY_NONCES-12A Hook may only use up to 256 calls to nonce() per execution. Further calls result in this error code.
TOO_MANY_EMITTED_TXN-13A Hook must declare ahead of time how many TXN it intends to emit().
If it emits fewer than this many, this is allowed.
If it emits more than this many this error is returned.
NOT_IMPLEMENTED-14While Hooks is/was in development an API may return this if some or all of that API is planned but not yet implemented.
INVALID_ACCOUNT-15An API which accepts a 20 byte Account ID may return this if, in its opinion, the Account ID was not valid for any reason.
GUARD_VIOLATION-16All loops inside a Hook must declare at the top of the loop, as the first non trivial instruction, before any branch instruction, the promised maximum number of iterations of the loop. If this promise is violated the hook terminates immediately with this error code.
INVALID_FIELD-17The requested serialized field could not be found in the specified object.
PARSE_ERROR-18While parsing serialized content an error was encountered (typically indicating an invalidly serialized object).
RC_ROLLBACK-19Used internally to communicate a rollback event.
RC_ACCEPT-20Used internally to communicate an accept event.
NO_SUCH_KEYLET-21Specified keylet could not be found, or keylet is invalid
NOT_AN_ARRAY-22API was asked to assume object under analysis is an STArray but it was not.
NOT_AN_OBJECT-23API was asked to assume object under analysis is an STObject but it was not.
INVALID_FLOAT-10024A floating point operation resulted in Not-A-Number or API call attempted to specify an XFL floating point number outside of the expressible range of XFL.
DIVISION_BY_ZERO-25API call would result in a division by zero, so API ended early.
MANITSSA_OVERSIZED-26When attempting to create an XFL the mantissa must be 16 decimal digits.
MANTISSA_UNDERSIZED-27When attempting to create an XFL the mantissa must be 16 decimal digits.
EXPONENT_OVERSIZED-28When attempting to create an XFL the exponent must not exceed 80.
EXPONENT_UNDERSIZED-29When attempting to create an XFL the exponent must not be less than -96.
OVERFLOW-30A floating point operation done on an XFL resulted in a value larger than XFL format is able to represent.
NOT_IOU_AMOUNT-31An API assumed an STAmount was an IOU when in fact it was XRP.
NOT_AN_AMOUNT-32An API assumed an STObject was an STAmount when in fact it was not.
CANT_RETURN_NEGATIVE-33An API would have returned a negative integer except that negative integers are reserved for error codes (i.e. what you are reading.)
NOT_AUTHORIZED-34Hook attempted to set foreign state but was not authorized to do so (grant was missing or invalid.)
PREVIOUS_FAILURE_PREVENTS_RETRY-35Hook previously received a NOT_AUTHORIZED return code and is not allowed to retry.
TOO_MANY_PARAMS-36Attempted to set a hook parameter for a later hook in the chain, but there are now too many parameters.
INVALID_TXN-37Serialized transaction was not a valid transaction (usually because of a missing required field or data corruption / truncation.)
RESERVE_INSUFFICIENT-38Setting an additional state object on this account would cause the reserve requirements to exceed the account's balance.
COMPLEX_NOT_SUPPORTED-39Hook API would be forced to return a complex number, which it cannot do.
DOES_NOT_MATCH-40Two arguments were required to be of the same type but are not.
INVALID_KEY-41The provided public key was not valid.
NOT_A_STRING-42The buffer did not contain a nul terminated string.
MEM_OVERLAP-43The writing pointer points to a buffer that overlaps with the reading pointer.