API Reference

All River Lightning API calls return JSON response bodies that include information about the resource or error information.

🚧

Please note that new JSON fields may be added to API responses at any point.

Errors

River Lightning uses conventional HTTP protocol status codes to indicate errors while success response status code will always be 200.

HTTP Status CodeCode Summary
200Everything worked as expected.
400The request was not processed normally.
401No valid API key or the requested account is not associated with the API key.
404The requested resource was not found.

Error Object

Attribute NameTypeDescription
category (required)stringThe category of the code
code (required)stringThe specific error code
error_paramstringThe name of the field in the original request that cause the error if there is any

Error Category

Error CategoryDescription
ACCOUNT_ERRORAn account-level error occurred.
API_ERRORA server error occurred on River Lightning's side.
AUTH_ERRORAn authentication error occurred. This usually means the request had a missing or invalid api key.
INVALID_REQUEST_ERRORThe request was invalid. This usually means the request was made with an invalid parameter or the resource already exists.
LIGHTNING_ERRORA lightning-specific error occurred.
ONCHAIN_ERRORAn onchain-specific error occurred.

Error Code

Error CodeError CategoryHTTP Status CodeDescriptionExtra Attributes in Returned Error Object
MISSING_API_KEYAUTH_ERROR401API Key is missing-
INVALID_API_KEYAUTH_ERROR401API Key is invalid. This could also happen if you use a API Key associated with another account-
INVALID_PARAMETERINVALID_REQUEST_ERROR400There is at least one parameter(from path, query params and body) in the request is invalid.error_param
MISSING_REQUIRED_PARAMETERINVALID_REQUEST_ERROR400There is at least one required parameter in the request is missing.error_param
NOT_FOUNDINVALID_REQUEST_ERROR404Requested resource is not found.-
RESOURCE_ALREADY_EXISTSINVALID_REQUEST_ERROR400The resource already exists-
REQUEST_PATH_WITH_TRAILING_SLASHINVALID_REQUEST_ERROR400Request path shouldn't end with trailing slash. A trailing slash might be added if a empty string identifier is used accidentally.-
INTERNAL_SERVER_ERRORAPI_ERROR500A General internal server occurred in River's end-
INVALID_DESTINATIONLIGHTNING_ERROR400The provided destination is not a valid.-
INVALID_INVOICELIGHTNING_ERROR400The provided invoice is not a valid. BOLT #11-
WITHDRAWAL_AMOUNT_MISMATCHLIGHTNING_ERROR400The amount in request parameter is not the same as the one encoded in invoice.-
ALREADY_PAID_INVOICELIGHTNING_ERROR400The invoice has already been paid.-
EXPIRED_INVOICELIGHTNING_ERROR400The invoice has expired.-
FAILED_TO_ESTIMATE_LIGHTNING_FEELIGHTNING_ERROR400The Fee Estimation for paying the lightining invoice failed.-
INSUFFICIENT_AVAILABLE_BALANCEACCOUNT_ERROR400The account doesn't have enough available balance for making the requested withdrawal.-
LNURL_SERVER_RETURNED_ERRORLIGHTNING_ERROR400LNURL Server returned error. This could happen if LNURL is used as destination in new withdrawal endpoint and the remote LNURL server return error or it's currently not operating normally-
LNURL_PAY_AMOUNT_HIGHER_THAN_MAX_SENDABLELIGHTNING_ERROR400The withdrawal amount specified in params is higher than maxSendable specified in Pay Params returned from LNURL server-
LNURL_PAY_AMOUNT_LOWER_THAN_MIN_SENDABLELIGHTNING_ERROR400The withdrawal amount specified in params is lower than minSendable specified in Pay Params returned from LNURL server-
LNURL_OVER_TOR_NOT_SUPPORTEDLIGHTNING_ERROR400TOR address in LNURL Pay is not supported yet-
LNURL_NON_PAY_PARAMS_RETURNEDLIGHTNING_ERROR400The LNURL server returned non Pay params-
LNURL_INVALID_INTERNET_IDENTIFIERLIGHTNING_ERROR400The provided internet identifier (domain) is not valid.-
LNURL_INVALID_USERNAMELIGHTNING_ERROR400The provided username is not valid; username may only contain lowercase characters, numbers, hyphen, underscore and period.-
FEE_LIMIT_TOO_LOWONCHAIN_ERROR400The fee limit was set too low for the fee level. Try getting a fee estimate from the onchain fee endpoint and increasing the buffer for the fee level.-
ADDRESS_FOR_WRONG_CHAINONCHAIN_ERROR400Onchain address is for the wrong chain, ensure you are using a mainnet Bitcoin address.-
AMOUNT_BELOW_MINIMUM_LIMITONCHAIN_ERROR400Onchain amount below 100,000 sat minimum.-