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

# Common Errors

> Troubleshoot common integration issues and API errors

## API Validation Errors

<AccordionGroup>
  <Accordion title="Request validation failed: failed to get policy ID for address">
    **Cause**: The provided address doesn't have an associated policy on the specified chain.

    **Solutions**:

    * Verify you have registered your contract address in the Predicate dashboard
    * Confirm you called `setRegistry()` and `setPolicyID()` on your contract
    * Ensure the contract's Policy ID matches your dashboard configuration
    * Ensure you're using a supported chain name

    **Example Error**:

    ```
    request validation failed: failed to get policy ID for address 0xa88274BD794c60B2F6FED3b471044c091Aea04E1
    ```
  </Accordion>

  <Accordion title="Missing required fields">
    **Cause**: Request is missing required transaction fields.

    **Solution**: Include all required fields in your request:

    ```json theme={null}
    {
      "from": "0x1234567890123456789012345678901234567890",
      "to": "0x1234567890123456789012345678901234567890",
      "chain": "ethereum"
    }
    ```

    `data` and `msg_value` are optional — only needed when using `PredicateClient` for function-level policy validation.

    **Example Error**: `Missing required field: from`
  </Accordion>

  <Accordion title="Unsupported chain ID">
    **Cause**: The specified chain ID is not supported by your configuration.

    **Solutions**:

    * Use a supported chain ID (check your dashboard for available chains)
    * Contact support to add chain support
    * Verify chain configuration in your environment

    **Example Error**: `unsupported chain ID 999`
  </Accordion>
</AccordionGroup>

## HTTP Status Errors

<AccordionGroup>
  <Accordion title="401 Unauthorized - Missing or invalid token">
    **Cause**: API key is missing, invalid, or expired.

    **Solutions**:

    * Include API key in request header: `x-api-key: YOUR_API_KEY`
    * Verify API key is active in the Predicate dashboard
    * Regenerate API key if needed
    * Check for typos in the API key

    **Headers Example**:

    ```bash theme={null}
    curl -H "x-api-key: YOUR_API_KEY" \
         -H "Content-Type: application/json" \
         https://api.predicate.io/v2/attestation
    ```
  </Accordion>

  <Accordion title="408 Request Timeout">
    **Cause**: Transaction validation took longer than 25 seconds.

    **Solutions**:

    * Retry the request with exponential backoff
    * Contact support if timeouts persist

    **Retry Logic Example**:

    ```typescript theme={null}
    const retryWithBackoff = async (fn, maxRetries = 3) => {
      for (let i = 0; i < maxRetries; i++) {
        try {
          return await fn();
        } catch (error) {
          if (error.status === 408 && i < maxRetries - 1) {
            await new Promise(resolve => setTimeout(resolve, Math.pow(2, i) * 1000));
            continue;
          }
          throw error;
        }
      }
    };
    ```
  </Accordion>

  <Accordion title="429 Rate Limited">
    **Cause**: Too many requests in a short time period.

    **Solutions**:

    * Implement exponential backoff in your retry logic
    * Review your rate limits in the dashboard
    * Consider upgrading your plan for higher limits (contact support)
  </Accordion>
</AccordionGroup>

## Integration Errors

<AccordionGroup>
  <Accordion title="Attestation verification failed">
    **Cause**: Attestation signature or format is incorrect for smart contract verification.

    **Solutions**:

    * Validate signature encoding is correct (most likely culprit)
    * Ensure you're using the latest `PredicateClient.sol`
    * Verify the request to Predicate API matches the encoding on the application Contract
  </Accordion>

  <Accordion title="Invalid Signature">
    **Cause**: The `data` and/or `msg_value` sent to the Predicate API don't match what the contract encodes onchain. The attestation is signed over these values, so any mismatch causes the onchain signature check to fail.

    This is the most common integration error when using `PredicateClient`. It does **not** apply to `BasicPredicateClient`, which omits `data` and `msg_value` entirely.

    **Solutions**:

    * **Switch to `BasicPredicateClient`** if your policy only validates *who* can transact (AML/KYC, allowlist/denylist, geo-restrictions). This eliminates calldata encoding entirely — the API request only needs `from`, `to`, and `chain`.
    * If you need `PredicateClient`, ensure the `data` field sent to the API is the exact output of `abi.encodeWithSignature` for the **internal** function your contract calls (e.g., `_deposit(uint256)`, not the external function).
    * Ensure `msg_value` matches the value the transaction will send onchain. Use `"0x0"` or `"0"` if no ETH is sent.
  </Accordion>
</AccordionGroup>