Skip to main content

​
API Validation Errors

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
Cause: Request is missing required transaction fields.Solution: Include all required fields in your request:
{
  "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
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

​
HTTP Status Errors

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:
curl -H "x-api-key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     https://api.predicate.io/v2/attestation
Cause: Transaction validation took longer than 25 seconds.Solutions:
  • Retry the request with exponential backoff
  • Contact support if timeouts persist
Retry Logic Example:
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;
    }
  }
};
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)

​
Integration Errors

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
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.