> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arcpass.vibepas.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshoot ArcPass Sponsorship Issues

> Step-by-step guidance for diagnosing and fixing common ArcPass problems including wallet errors, stuck requests, rate limits, and failed relay transactions.

If something goes wrong with your sponsorship request, this page covers the most common errors and how to resolve them. Each issue includes the likely cause and the specific steps you should take. If none of these apply to your situation, check the dashboard worker health status or contact the infrastructure team.

<AccordionGroup>
  <Accordion title="&#x22;Wallet not found&#x22; error when requesting sponsorship">
    **Cause:** You are trying to request sponsorship for a wallet address that has not been registered with ArcPass yet. The API requires the wallet to exist in the database before a sponsorship request can be created.

    **Fix:** Register the wallet first by calling:

    ```http theme={null}
    POST /wallets/register
    Content-Type: application/json

    {
      "walletAddress": "0xYourWalletAddressHere"
    }
    ```

    Once registration succeeds, submit your sponsorship request again with the same wallet address.
  </Accordion>

  <Accordion title="&#x22;Already sponsored&#x22; or rejected request status">
    **Cause:** Your wallet has already received a sponsorship. The `SponsorshipRegistry` contract on-chain records every sponsored wallet permanently, and `isSponsored()` returns `true` for your address. ArcPass enforces a one-sponsorship-per-wallet limit at the contract level.

    **Fix:** This is expected behavior and cannot be overridden. To confirm the on-chain state yourself, you can call the `SponsorshipRegistry` contract directly:

    ```solidity theme={null}
    SponsorshipRegistry.isSponsored(yourAddress) // returns true
    ```

    If you believe this is an error — for example, you never received gas despite the registry showing `true` — contact the infrastructure team with your wallet address and the transaction hash from the relay record.
  </Accordion>

  <Accordion title="Request stuck in pending status for a long time">
    **Cause:** The relay worker may be experiencing a processing delay or backlog. The worker processes pending requests every 5 seconds by default, but high load, a slow network response, or a temporary worker restart can delay processing.

    **Fix:** Wait a few minutes and check your request status again using:

    ```http theme={null}
    GET /sponsorship/{your-request-id}
    ```

    You can also check the `/dashboard` for worker health indicators. If the worker shows as unhealthy or requests have been in `pending` state for more than 10–15 minutes without movement, the infrastructure team monitors service health and will investigate.
  </Accordion>

  <Accordion title="&#x22;Rate limited&#x22; (429 error)">
    **Cause:** Your IP address or wallet address has exceeded the allowed number of requests within the current rate limit window. By default, a single IP can send up to 10 requests per hour and a single wallet can appear in up to 5 requests per hour. Exceeding either threshold triggers an automatic 15-minute block.

    **Fix:** Wait for the block period to expire — it lasts **15 minutes** by default — then try your request again. There is no way to manually reset the limit. If you are hitting rate limits during normal use (not testing or automation), something in your client may be sending duplicate requests. Check the [rate limits reference](/configuration/rate-limits) for more details on how the windows and thresholds work.
  </Accordion>

  <Accordion title="Request shows &#x22;failed&#x22; status after processing">
    **Cause:** The relay worker attempted to submit your transaction on-chain but encountered an error — most commonly a network connectivity issue with the RPC endpoint or insufficient balance in the `SponsorVault` treasury. The worker retries failed relay attempts automatically.

    **Fix:** The system retries your request up to **5 times** before marking it as permanently failed. If the status is `failed` and no further retries are pending, you can submit a new sponsorship request:

    ```http theme={null}
    POST /sponsorship/request
    Content-Type: application/json

    {
      "walletAddress": "0xYourWalletAddressHere"
    }
    ```

    A new request starts the relay process from the beginning. If requests continue to fail after multiple attempts, the vault may have insufficient funds — this is an operator-level issue and the infrastructure team will need to top up the treasury.
  </Accordion>

  <Accordion title="Invalid wallet address error">
    **Cause:** The wallet address you submitted does not match the required format. ArcPass validates all addresses against the pattern `^0x[0-9a-fA-F]{40}$` — a `0x` prefix followed by exactly 40 hexadecimal characters (42 characters total).

    **Fix:** Double-check your wallet address. Common mistakes include:

    * Missing the `0x` prefix
    * An address that is too short or too long (should be exactly 42 characters)
    * Non-hexadecimal characters in the address body
    * Copying extra whitespace before or after the address

    Once you have confirmed the address is correctly formatted, resubmit your request.
  </Accordion>

  <Accordion title="Service appears offline on the dashboard">
    **Cause:** The API or worker service may be temporarily unavailable due to a deployment, restart, or infrastructure issue.

    **Fix:** Wait a few minutes and check the dashboard again. ArcPass services are monitored by the infrastructure team and outages are investigated automatically. If the service remains unavailable for an extended period, report the issue through the project's GitHub repository. Do not repeatedly retry requests during a known outage, as this may interact with rate limit counters.
  </Accordion>
</AccordionGroup>