UMA logo
UMA logo

Error Handling

The UMA Standard defines a set of standardized error codes that enable communication between VASPs when issues occur. These error codes are particularly useful for receiving VASP implementations that need to communicate specific problems back to sending VASPs during request processing. For example, when a sending VASP sends an UMA message and your receiving VASP encounters an issue (like invalid signatures or missing metadata), you can return the appropriate error code to clearly explain what went wrong. The UMA SDKs simplify this process by throwing these errors when they detect issues and providing utilities to convert them into standardized JSON responses that VASPs can easily interpret and handle.
# raises UmaException
verify_uma_lnurlp_query_signature(
    request=lnurlp_request,
    other_vasp_pubkeys=sender_vasp_pubkey_response,
    nonce_cache=self.nonce_cache,
)

@app.errorhandler(UmaException)
def handle_uma_exception(e):
    return jsonify(json.loads(e.to_json())), e.to_http_status_code()
You can also throw these errors yourself, when you encounter an error case that is not raised by the SDKs.
target_currency = next(
    (currency for currency in currencies if currency.code == currency_code),
    None,
)
if not target_currency:
    raise UmaException(
        f"Currency code {currency_code} is not supported.",
        ErrorCode.INVALID_CURRENCY,
    )

if amount < target_currency.min_sendable or amount > target_currency.max_sendable:
    raise UmaException(
        f"Amount is out of range. Must be between {target_currency.min_sendable} " +
          f"and {target_currency.max_sendable}. Amount was {amount}.",
        ErrorCode.AMOUNT_OUT_OF_RANGE,
    )

Error Codes

You can find the full list of error codes below. If you run into an error that is not listed here, feel free to create a Pull Request or an issue at the UMA Protocol GitHub repository and we'll add it to the list!
  • COUNTERPARTY_PUBKEY_FETCH_ERROR: Error fetching counterparty public key for validating signatures or encrypting messages
  • INVALID_PUBKEY_FORMAT: Error parsing the counterparty public key response
  • CERT_CHAIN_INVALID: The provided certificate chain is invalid
  • CERT_CHAIN_EXPIRED: The provided certificate chain has expired
  • INVALID_SIGNATURE: The provided signature is not valid
  • INVALID_TIMESTAMP: The provided timestamp is not valid
  • INVALID_NONCE: The provided nonce is not valid
  • INTERNAL_ERROR: An unexpected error occurred on the server
  • NON_UMA_LNURL_NOT_SUPPORTED: This party does not support non-UMA LNURLs
  • MISSING_REQUIRED_UMA_PARAMETERS: Missing required UMA parameters
  • UNSUPPORTED_UMA_VERSION: The counterparty UMA version is not supported
  • PARSE_LNURLP_REQUEST_ERROR: Error parsing the LNURLP request
  • VELOCITY_LIMIT_EXCEEDED: This user has exceeded the velocity limit and is unable to receive payments at this time
  • USER_NOT_FOUND: The user for this UMA was not found
  • USER_NOT_READY: The user for this UMA is not ready to receive payments at this time
  • REQUEST_NOT_FOUND: The request corresponding to this callback URL was not found
  • PARSE_PAYREQ_REQUEST_ERROR: Error parsing the payreq request
  • AMOUNT_OUT_OF_RANGE: The amount provided is not within the min/max range
  • INVALID_CURRENCY: The currency provided is not valid or supported
  • SENDER_NOT_ACCEPTED: Payments from this sender are not accepted
  • MISSING_MANDATORY_PAYER_DATA: Payer data is missing fields that are required by the receiver
  • UNRECOGNIZED_MANDATORY_PAYEE_DATA_KEY: Receiver does not recognize the mandatory payee data key
  • PARSE_UTXO_CALLBACK_ERROR: Error parsing the utxo callback
  • COUNTERPARTY_NOT_ALLOWED: This party does not accept payments with the counterparty
  • PARSE_LNURLP_RESPONSE_ERROR: Error parsing the LNURLP response
  • PARSE_PAYREQ_RESPONSE_ERROR: Error parsing the payreq response
  • LNURLP_REQUEST_FAILED: The LNURLP request failed
  • PAYREQ_REQUEST_FAILED: The payreq request failed
  • NO_COMPATIBLE_UMA_VERSION: No compatible UMA protocol version found between sender and receiver
  • INVALID_INVOICE: The provided invoice is invalid
  • INVOICE_EXPIRED: The invoice has expired
  • QUOTE_EXPIRED: The quote has expired
  • INVALID_INPUT: The provided input is invalid
  • INVALID_REQUEST_FORMAT: The request format is invalid
  • FORBIDDEN: This action is not permitted for this user
  • NOT_IMPLEMENTED: This functionality is not implemented
  • QUOTE_NOT_FOUND: The requested quote was not found