Common Stellar Lumens Error Codes and How to Fix Them

2/8/2023, 8:41:48 AM - Henry Chikwem
Common Stellar Lumens Error Codes and How to Fix Them

What is Stellar Lumens?

Stellar is a distributed ledger built on the blockchain that aims to link individuals and financial institutions all over the world. Stellar’s mission is to improve financial inclusion by developing accessible, low-cost, and simple-to-use global payment systems.

The Stellar Development Foundation is the name of the network that is being created. Stellar lumens is the network’s currency. Stellar lumens is denoted by the sign XLM.

Many people throughout the globe are still unbanked, and Stellar aims to provide universal access and participation in the global economy.

Expecting the unexpected while working with a payment network like Stellar is crucial to maintaining a positive user experience, and as a result, failures do occur as long as Stellar is involved.

Common Stellar Lumens Error Codes and How to Fix Them

We bring to you a list of some common errors in Stellar, and how to fix them:

Common Errors on Stellar Lumens

1. Timeouts

If you receive a 504 Timeout from Horizon after submitting a transaction, you’ve come across something a bit vague and non-traditional in the Stellar universe: timeouts are more of a warning that your request hasn’t been performed within a fair length of time yet than an error.

This nuance derives from the nature of Horizon’s interaction with Stellar Core: the network may take some time to approve a transaction, especially one with a modest fee, on the order of 5-10 minutes under congestion, whereas Horizon must respond to developers within an acceptable 30 seconds or so.

When you obtain a 504 error after you have sent your transaction, it does not mean that the transaction didn’t get to your network; rather, what it means is that you should keep retrying till the right result shows up.

If you keep getting timeouts on retries, you might want to consider using a fee-bump transaction to get into the ledger (after the time bounds have expired, of course) or increasing the maximum amount you’re ready to pay.

SEE ALSO: How Long Does a Stellar Lumens XLM Transfer Take?

2. Insufficient Fees and Surge Pricing

Surge pricing may apply when the Stellar network experiences surges of activity. This and changes in fees might result in unforeseen circumstances when you submit a transaction in programs that are not adjusted for changes in fees. One can handle these using two main methods:

A. Monitor charge variations using the fee stats API. This allows you to make educated, detailed decisions regarding the cost you’re willing to pay.

B. Set the highest fee you are willing to accept. Importantly, keep in mind that this does not imply that you will pay that amount on every purchase. You will only pay what is required to enter the ledger: in regular (non-surge) conditions, even if a higher maximum fee is specified, you will pay the usual fee (100 Stroops as of this writing).

The latter technique strikes a compromise between simplicity, efficacy, and convenience, but it can still lead to failure unless you set your limit high enough such that it is never surpassed. The former technique can give more dependable submissions by providing stronger guarantees about whether a transaction will be allowed or not.

In general, it’s critical to monitor fee costs: if the network saturates above your maximum willingness to pay, either waiting for activity to quiet down or retrying with the same charge is the best solution for your use case.

3. Fee increases on previous purchases

Even with a liberal fee-paying policy, your transaction may fail to enter the ledger because of inadequate cash or late surges. The purpose of a fee-bump transaction is to solve this difficulty.

If two different transactions are submitted given that they have the same origination account and sequence number, with the second transaction being an increased fee transaction, the second transaction will take the place of the first transaction in the transaction queue, the only condition being that its bidding cost is ten times the bidding cost of the first transaction at the very least.

This amount is often seen in the transaction response’s fee charged field under the tx insufficient fee error scenario.

SEE ALSO: How to Mine Stellar Lumens In a Nutshell

4.  Rate Limiting

When you exceed the rate limitations when utilizing the SDF’s public Horizon instance, you may receive a 429 Too Many Requests error. If you’re seeing this a lot, it might be time to set up your own Horizon instance.

5. Transaction Failed

When a client submits a transaction that was well-formed but was not included in the ledger due to some other issue, the transaction failed error returns a 400 error code.

A transaction, for example, may fail if:

A. The source account for the transaction is unable to pay the minimum charge.

B. There is an error in the sequence number.

C. One of the included activities, such as a payment transaction that overdraws the paying account, has failed.

This error nearly always means that the transaction provided in the original request will never succeed.

There is one exception: if the sequence number used in the transaction was too high, a transaction that fails with the tx bad seq result code (as indicated in the result code field of the error) may become legitimate in the future.

6. Transaction Malformed

When a client submits a faulty transaction, the transaction malformed error provides a 400 error code.

A transaction can be malformed in a variety of ways, including:

A. You provided an empty string.

B. The base64-encoded string you provided is invalid.

C. Your XDR structure is incorrect.

D. You have bytes leftover in your XDR structure.

SEE ALSO: How to Store Stellar Lumens XLM on Ledger Nano S

7. Before History

A Horizon server may be configured to preserve only a subset of the stellar network’s history in its database.

The before history error yields a 410 error number and happens when a client requests data (such as a page of transactions or a single operation) that the server can identify as being outside the range of recorded history.

8.  Stale History

A Horizon server can be set to refuse historical queries if the history is known to be more than a certain amount of time out of date.

In such circumstances, the stale history problem occurs and a 503 error code is returned.

To resolve this problem (assuming you are the operator of the Horizon instance), please confirm that the ingestion system is up and functioning and that fresh ledgers are being imported.

How to Fix Errors

Even though there are several methods to interact with the Stellar network via the Horizon API, the potential actions are divided into two categories: inquiries (any GET request, such as to /accounts) and transaction submissions (a POST to /transactions). Though there are a plethora of different error codes (we’ll go over some of them later), they may be addressed using a few key strategies:

A. The first line of defense is to adjust the request to resolve structural errors with queries or transaction submissions: If you included a bad parameter, malformed your XDR, or otherwise did not follow the endpoint’s specification, the error can be resolved by referencing the details or result codes of the error response.

B. Retrying until success is the recommended method for dealing with latency or congestion difficulties that may arise anywhere in the pipeline between your system and the Stellar network. Because of the nature of a distributed system, this ephemeral scenario is inescapable.

C. Adjusting the transaction can also alleviate difficulties, but only with great caution: if one of the foregoing possibilities is in play, it is possible to activate damaging duplicate actions (like sending a payment twice).

Let’s take a closer look at these tactics. The major case we’ll look at is transaction submission because it’s an activity with real-world consequences rather than a read-only request.

SEE ALSO: What To Know About Stella Lumen Consensus Protocol

1.  Request Modifications

Some problems cannot be resolved without modifying the request itself.

2. Queries

Many GET requests have particular parameter requirements, and while the SDKs can assist with these, you may still supply improper parameters (e.g. an asset string that isn’t SEP-11 conformant) that cause the request to fail every time. There is nothing you can do in this situation other than strictly adhere to the API standard.

3. Submission of Transactions

Certain transaction submission failures also need changes to be successful.

If the XDR is incorrect or the transaction is otherwise illegitimate, you will receive a 400 Bad Request error (for example, when excluding a source account as seen in the API reference example).

Another type of safe adjustment is transaction fees: if you receive a tx insufficient fee error, make sure you alter your fee-paying approach.

There are several instances (for example, 504 Timeouts, transitory outages, and Stellar network congestion) in which retrying your transaction submission is the only realistic option.

However, this should be regarded as the final line of protection; many times, the problem may be corrected by a safe update to the transaction.

Because there is no way to “cancel” a transaction after it has been submitted, the first key to effective retries is utilizing time bounds: time bounds, although optional, allow you to infuse a modicum of determinism into an otherwise non-deterministic system.

If the time limit is surpassed, the transaction has a clear end state: it either made it into the ledger or it timed out. The second key is derived from a Horizon guarantee: you may safely repeat submission as long as you do not change the transaction.

If the transaction has previously been successfully applied to the ledger, Horizon will simply return the stored result rather than attempting to submit the transaction again.

Only when the status of a transaction is unclear (and therefore has a chance of being included in a ledger) will it be resubmitted to the network.

In other words, if your transaction is successful at any point in time, you will receive your already filed transaction for any subsequent retries.

4. Unsafe Transaction Adjustments

It is always safe to resubmit an unaltered (and valid) transaction (with the same actions, signatures, sequence number, and so on).

However, you should exercise caution when working around a mistake that does necessitate modifications to the transaction: it is quite possible to produce duplicate transactions, which may cause a slew of issues (double-payments, erroneous trust lines, etc.).

Assuming transactions are submitted from various points in your application and the “Send Payment” button was tapped multiple times, only one transaction will be successful for each tap you send.  

The others will fail due to an incorrect sequence number, and if you resubmit blindly with a modified sequence number, these payments will also succeed, resulting in many payments being made when only one was intended.

In essence, resubmitting transactions that have been updated to work around a mistake should be done with extreme caution.

Final Thoughts

This article brings to you various common Stellar Lunar error codes and how they can be fixed. It is important to understand the different kinds of errors that are typically encountered and how to go about them. That is what you will find here and much more.

Read More