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 Code | Code Summary |
|---|---|
| 200 | Everything worked as expected. |
| 400 | The request was not processed normally. |
| 401 | No valid API key or the requested account is not associated with the API key. |
| 404 | The requested resource was not found. |
Error Object
Error Category
| Error Category | Description |
|---|---|
| ACCOUNT_ERROR | An account-level error occurred. |
| API_ERROR | A server error occurred on River Lightning's side. |
| AUTH_ERROR | An authentication error occurred. This usually means the request had a missing or invalid api key. |
| INVALID_REQUEST_ERROR | The request was invalid. This usually means the request was made with an invalid parameter or the resource already exists. |
| LIGHTNING_ERROR | A lightning-specific error occurred. |
| ONCHAIN_ERROR | An onchain-specific error occurred. |
Error Code
| Error Code | Error Category | HTTP Status Code | Description | Extra Attributes in Returned Error Object |
|---|---|---|---|---|
| MISSING_API_KEY | AUTH_ERROR | 401 | API Key is missing | - |
| INVALID_API_KEY | AUTH_ERROR | 401 | API Key is invalid. This could also happen if you use a API Key associated with another account | - |
| INVALID_PARAMETER | INVALID_REQUEST_ERROR | 400 | There is at least one parameter(from path, query params and body) in the request is invalid. | error_param |
| MISSING_REQUIRED_PARAMETER | INVALID_REQUEST_ERROR | 400 | There is at least one required parameter in the request is missing. | error_param |
| NOT_FOUND | INVALID_REQUEST_ERROR | 404 | Requested resource is not found. | - |
| RESOURCE_ALREADY_EXISTS | INVALID_REQUEST_ERROR | 400 | The resource already exists | - |
| REQUEST_PATH_WITH_TRAILING_SLASH | INVALID_REQUEST_ERROR | 400 | Request path shouldn't end with trailing slash. A trailing slash might be added if a empty string identifier is used accidentally. | - |
| INTERNAL_SERVER_ERROR | API_ERROR | 500 | A General internal server occurred in River's end | - |
| INVALID_DESTINATION | LIGHTNING_ERROR | 400 | The provided destination is not a valid. | - |
| INVALID_INVOICE | LIGHTNING_ERROR | 400 | The provided invoice is not a valid. BOLT #11 | - |
| WITHDRAWAL_AMOUNT_MISMATCH | LIGHTNING_ERROR | 400 | The amount in request parameter is not the same as the one encoded in invoice. | - |
| ALREADY_PAID_INVOICE | LIGHTNING_ERROR | 400 | The invoice has already been paid. | - |
| EXPIRED_INVOICE | LIGHTNING_ERROR | 400 | The invoice has expired. | - |
| FAILED_TO_ESTIMATE_LIGHTNING_FEE | LIGHTNING_ERROR | 400 | The Fee Estimation for paying the lightining invoice failed. | - |
| INSUFFICIENT_AVAILABLE_BALANCE | ACCOUNT_ERROR | 400 | The account doesn't have enough available balance for making the requested withdrawal. | - |
| LNURL_SERVER_RETURNED_ERROR | LIGHTNING_ERROR | 400 | LNURL 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_SENDABLE | LIGHTNING_ERROR | 400 | The withdrawal amount specified in params is higher than maxSendable specified in Pay Params returned from LNURL server | - |
| LNURL_PAY_AMOUNT_LOWER_THAN_MIN_SENDABLE | LIGHTNING_ERROR | 400 | The withdrawal amount specified in params is lower than minSendable specified in Pay Params returned from LNURL server | - |
| LNURL_OVER_TOR_NOT_SUPPORTED | LIGHTNING_ERROR | 400 | TOR address in LNURL Pay is not supported yet | - |
| LNURL_NON_PAY_PARAMS_RETURNED | LIGHTNING_ERROR | 400 | The LNURL server returned non Pay params | - |
| LNURL_INVALID_INTERNET_IDENTIFIER | LIGHTNING_ERROR | 400 | The provided internet identifier (domain) is not valid. | - |
| LNURL_INVALID_USERNAME | LIGHTNING_ERROR | 400 | The provided username is not valid; username may only contain lowercase characters, numbers, hyphen, underscore and period. | - |
| FEE_LIMIT_TOO_LOW | ONCHAIN_ERROR | 400 | The 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_CHAIN | ONCHAIN_ERROR | 400 | Onchain address is for the wrong chain, ensure you are using a mainnet Bitcoin address. | - |
| AMOUNT_BELOW_MINIMUM_LIMIT | ONCHAIN_ERROR | 400 | Onchain amount below 100,000 sat minimum. | - |