Return Codes

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.

Name	Value	Description
SUCCESS	>= 0	Non-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	-1	A pointer or buffer length provided as a parameter described memory outside of the Hook's allowed memory region.
INTERNAL_ERROR	-2	Reserved for internal invariant trips, generally unrelated to inputs. These should be reported with an issue.
TOO_BIG	-3	Attempted to set a parameter or value larger than the allowed space.
TOO_SMALL	-4	The API was unable to produce output to the write_ptr because the specified write_len was too small.
DOESNT_EXIST	-5	The requested object or item wasn't found.
NO_FREE_SLOTS	-6	The 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	-7	One or more of the parameters to the API were invalid according to the individual API's specification.
ALREADY_SET	-8	Some 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	-9	An API required the Hook to do something before the API is allowed to be called. Check the API's documentation.
FEE_TOO_LARGE	-10	During fee calculation if an absurdly large fee is calculated this error is returned.
EMISSION_FAILURE	-11	An 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	-12	A Hook may only use up to 256 calls to nonce() per execution. Further calls result in this error code.
TOO_MANY_EMITTED_TXN	-13	A 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	-14	While 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	-15	An 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	-16	All 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	-17	The requested serialized field could not be found in the specified object.
PARSE_ERROR	-18	While parsing serialized content an error was encountered (typically indicating an invalidly serialized object).
RC_ROLLBACK	-19	Used internally to communicate a rollback event.
RC_ACCEPT	-20	Used internally to communicate an accept event.
NO_SUCH_KEYLET	-21	Specified keylet could not be found, or keylet is invalid
NOT_AN_ARRAY	-22	API was asked to assume object under analysis is an STArray but it was not.
NOT_AN_OBJECT	-23	API was asked to assume object under analysis is an STObject but it was not.
INVALID_FLOAT	-10024	A 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	-25	API call would result in a division by zero, so API ended early.
MANITSSA_OVERSIZED	-26	When attempting to create an XFL the mantissa must be 16 decimal digits.
MANTISSA_UNDERSIZED	-27	When attempting to create an XFL the mantissa must be 16 decimal digits.
EXPONENT_OVERSIZED	-28	When attempting to create an XFL the exponent must not exceed 80.
EXPONENT_UNDERSIZED	-29	When attempting to create an XFL the exponent must not be less than -96.
OVERFLOW	-30	A floating point operation done on an XFL resulted in a value larger than XFL format is able to represent.
NOT_IOU_AMOUNT	-31	An API assumed an STAmount was an IOU when in fact it was XRP.
NOT_AN_AMOUNT	-32	An API assumed an STObject was an STAmount when in fact it was not.
CANT_RETURN_NEGATIVE	-33	An API would have returned a negative integer except that negative integers are reserved for error codes (i.e. what you are reading.)
NOT_AUTHORIZED	-34	Hook attempted to set foreign state but was not authorized to do so (grant was missing or invalid.)
PREVIOUS_FAILURE_PREVENTS_RETRY	-35	Hook previously received a NOT_AUTHORIZED return code and is not allowed to retry.
TOO_MANY_PARAMS	-36	Attempted to set a hook parameter for a later hook in the chain, but there are now too many parameters.
INVALID_TXN	-37	Serialized transaction was not a valid transaction (usually because of a missing required field or data corruption / truncation.)
RESERVE_INSUFFICIENT	-38	Setting an additional state object on this account would cause the reserve requirements to exceed the account's balance.
COMPLEX_NOT_SUPPORTED	-39	Hook API would be forced to return a complex number, which it cannot do.
DOES_NOT_MATCH	-40	Two arguments were required to be of the same type but are not.
INVALID_KEY	-41	The provided public key was not valid.
NOT_A_STRING	-42	The buffer did not contain a nul terminated string.
MEM_OVERLAP	-43	The writing pointer points to a buffer that overlaps with the reading pointer.
TOO_MANY_STATE_MODIFICATIONS	-44	More than 5000 modified state entries in the combined hook chains
TOO_MANY_NAMESPACES	-45	More than 256 namespaces on this account