> For the complete documentation index, see [llms.txt](https://docs.talus.network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.talus.network/guides/nexus-api/troubleshooting.md). # Nexus API Troubleshooting {% hint style="info" %} **Audience:** External dApp and service developers seeing an unexpected hosted API response. **Goal:** Distinguish credential, projection, cursor, rate-limit, and transport failures, then apply a bounded recovery action. {% endhint %} Start with the HTTP status, content type, x-request-id, and x-error-code when the response actually contains the ordinary JSON error envelope. A 408, 413, or malformed-request response may be envelope-free, so preserve bounded body text and do not assume error\_code exists. The architecture figure turns a vague failure into a public consumer decision: credential failures stop reconnect loops, retryable reads stay bounded, and event disconnects use a validated cursor only under the provider's published retention/reset contract rather than by guessing state. The sequence preserves the provider boundary: the consumer can correct its key handling and retry policy, while service-side projection or deployment problems are reported with the request id rather than diagnosed through unpublished internals. ### At a glance | Symptom | Meaning | Safe next action | | -------------------------- | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | 401 missing or invalid key | The credential was absent, malformed, revoked, or expired | Confirm the exact server-side header and ask the provider to rotate the key | | 403 insufficient scope | The key is valid but does not cover this resource family | Request the smallest additional scope through the provider's secure channel | | 404 detail path | The deployment has no indexed row for that identifier | Check the deployment URL and network identity before retrying | | 408 without JSON | The request exceeded the service timeout layer | Narrow filters or page size and retry once under the read policy | | 413 without JSON | The request or response exceeded a body limit | Reduce the request or page before retrying | | 429 | A scoped bucket is empty | Honor Retry-After or ratelimit-reset with bounded backoff | | 5xx | Hosted projection or transport failure | Preserve x-request-id, retry idempotent reads, and report repeated failure to the provider | | Empty list | The query matched nothing or projection state is behind | Verify filters, wait for indexed state, and re-read | | Stream prints nothing | The network may be quiet, or the request may have been rejected before streaming | Check the HTTP status first; observe keep-alives only after a 200 response | | Stream disconnects | The transport closed or the service restarted | Reconnect with the last validated id when the provider contract supports it, validate/deduplicate frames, and re-read affected REST state | #### Empty is an answer, sometimes A 200 list with empty items means the query completed and matched no projected rows. A new on-chain change may arrive on the event stream before the projection and response cache show it. Keep the last event id, mark the UI as syncing, and re-read instead of turning an empty page into a deletion claim. A 404 detail response means this deployment does not know the identifier. Check that the provisional URL points at the intended network and that the resource family is covered by the key scope. #### A silent stream Keep-alive comments distinguish a quiet 200 stream from a dead connection. EventSource hides comments by design, while curl can display them; cadence is provider-specific. An unknown kinds filter is rejected with HTTP 400 and `INVALID_FILTER_VALUE`; it is not a silent stream. A cursor from a different deployment or beyond retention can be clamped or rejected according to the provider's public behavior; validate and deduplicate frames, discard a rejected cursor, and start at the current tip only when the provider documents that recovery. Use `/openapi.json` and the provider's retention/reset policy as the authority. Treat a 401 or 403 stream response as fatal until the provider corrects the credential. Treat a disconnect, 408, 429, or 5xx as retryable only with bounded backoff. On every reconnect, persist a cursor only after parsing and validating a complete event frame; if the provider rejects that cursor, clear it before restarting rather than looping on the same request. #### Relay and browser failures If the browser sees x-api-key, the relay boundary is broken: remove the key from browser code and keep it in the server process. If the relay returns unexpected cookies, redirects, authentication challenges, CSP, upstream cache, or body-framing headers, restore the allowlist policy from the [dApp guide](/guides/nexus-api/connect-a-dapp.md) and rerun its relay tests. If a response is rendered as markup or an event contains an unexpected shape, close the stream, validate JSON and bounded fields, and show a retry action. Use text nodes or framework text rendering rather than inserting service strings as HTML. #### When to contact the provider Include the provisional URL, endpoint path, timestamp, status, bounded response detail, x-request-id, and last event id. Never include the API key or other secret. Repeated projection lag, unexplained 5xx responses, or a schema mismatch belongs with the service provider because the consumer has no public operational access. #### Next Return to [Step 1 — Configure Hosted API Access](/guides/nexus-api/tutorial/01-get-a-key.md) to re-establish the secret boundary, or consult the [document](https://api.taluslabs.dev/docs). --- # 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 following URL with the `ask` and `goal` query parameters: ``` GET https://docs.talus.network/guides/nexus-api/troubleshooting.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `build a script that syncs our docs to a CMS` lets GitBook tailor the answer to that use case. 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.