> For the complete documentation index, see [llms.txt](https://use.temporal.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://use.temporal.xyz/nozomi/troubleshooting.md). # Troubleshooting Most "Nozomi isn't landing my transactions" reports come down to a handful of causes. Work through this page before opening a ticket. ## Transaction Outcomes | Outcome | Meaning | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Landed** | The transaction was included in a block. | | **Succeeded** | It landed **and** executed without error. | | **Reverted** | It landed but failed on-chain (e.g. slippage, program error). You still land. Because the tip is an instruction inside the transaction, a reverted transaction that includes the tip still pays. | | **Expired** | The transaction expired before landing. Either the blockhash expired, or, for a durable-nonce transaction, the nonce was already advanced by another transaction. | A low **success** rate with a healthy **landing** rate is an on-chain problem (slippage, competition, program logic), not a delivery problem. ## How a Slot Is Won What wins you a slot: * **Your tip.** Nozomi orders transactions by tip and uses it to bid with the block builders it routes through (such as Jito and Harmonic), so on a block-builder path your tip drives ordering. When tips are equal, earlier arrival wins. * **Your priority fee.** This matters on its own when you land through a path that is not a block builder. Whether it helps depends on your strategy, so test it rather than assuming. When multiple transactions touch the **same writable account**, they compete in an auction over that conflicting state. More than one can still land in the same slot; your tip wins you position in that auction. See [Tipping → How prioritization works](/nozomi/tipping-and-faq.md#how-prioritization-works) for how to tune your bid. ## Common Self-Inflicted Causes * **Durable nonces.** Block builders may deprioritize durable-nonce transactions because they are associated with spam, so they can hurt landing on some paths (not always). Benchmark your flow with and without durable nonces to see which lands better. See [Tipping → Retries](/nozomi/tipping-and-faq.md#retries). * **Tip below the minimum.** Transactions tipping under the minimum are **silently dropped**: no error is returned. See [Tipping → Overview](/nozomi/tipping-and-faq.md#overview). * **Over-requested compute units.** If you set a priority fee, it is measured per compute unit, so requesting more compute units than your transaction uses dilutes it. Set a compute unit limit that reflects actual usage. * **Client-side retry loops.** Nozomi already retries server-side. Re-sending the same transaction yourself burns your rate limit and lowers your priority. See [FAQ → Rate Limits](/nozomi/faq.md#rate-limits). * **Low priority.** A high failure rate lowers your priority. See [FAQ → Priority](/nozomi/faq.md#priority). ## Benchmarking Correctly When you compare two setups, make sure the test is actually valid: * **Do not** race two paths with the **same durable nonce** or the **identical signed transaction**: only one can land, so the comparison is meaningless. * Allow a **warm-up period** on a newly issued key: your priority builds as your landing rate is observed. * Send each transaction **once per key**. Fan the same signed transaction out to **multiple regions** (limits are per-region) rather than duplicating it on one endpoint. See [FAQ → Rate Limits](/nozomi/faq.md#rate-limits). ## Error Reference | Status | Meaning | | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | `400` | Bad request: encoding, size, framing, or an insufficient/missing tip. | | `401` | Missing or invalid API key. Pass it as `?c=`. There is **no IP whitelisting**; a 401 always means the key is wrong. | | `429` | Rate limited: you exceeded your per-key, per-region limit, or your traffic was flagged as spam. See [FAQ → Rate Limits](/nozomi/faq.md#rate-limits). | | `500` | Internal error: retry. | A transient `invalid instruction data` response is usually safe to retry. If it persists, send support the transaction signature. ## Escalating If you have ruled out the above, open a ticket with **example transaction signatures** and the **slot/epoch** you expected them to land in. That lets support trace the delivery path. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://use.temporal.xyz/nozomi/troubleshooting.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.