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

# API errors

> Every Proofable API error code explained: what triggers it, what the response body means, and the exact recovery step for each case.

Responses use a typed `ErrorResponse` object: `success`, `error.code`, `error.message`, and optional `error.type`. Fix the request, retry with backoff, or route to hosted verify. Agents should parse `error.code` and honor `Retry-After` on `429`.

The same schema is published on every public operation in [Proofable OpenAPI](https://api.proofable.me/openapi.json).

## Error Response

```json theme={"system"}
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable message",
    "type": "error_type"
  },
  "requestId": "req_..."
}
```

## Common Error Codes

| Code | Meaning | What to do |
| - | - | - |
| `SIGNATURE_VERIFICATION_FAILED` | Verification request signature failed | Re-standardize, sign the returned string, and retry |
| `INVALID_SIGNATURE` | Signature format or context is invalid | Rebuild the signing flow and retry |
| `EXPIRED_SIGNATURE` | Signature timestamp is too old | Generate a fresh request and sign again |
| `INVALID_WALLET` | Wallet address format is invalid | Fix the request before retrying |
| `INVALID_VERIFIER_DATA` | Verifier inputs are missing or malformed | Check the verifier's required fields and retry |
| `INVALID_VERIFIER_COMBINATION` | Requested verifiers can't be combined in one request | Split into separate requests |
| `INVALID_VERIFIER_FLOW_COMBINATION` | A hosted-only verifier was mixed with others | Run the hosted-only check on its own |
| `VERIFICATION_FAILED` | The requested check did not pass | Treat as a failed verification, not a transport error |
| `NOT_FOUND` | Proof or resource not found | Confirm the id and visibility |
| `PROOF_NOT_FOUND` | Gate/fulfill proof not found | Confirm the gate and the proof exist |
| `WALLET_AUTH_REQUIRED` | Action needs an owner wallet signature/session | Authenticate the right wallet, then retry |
| `RATE_LIMIT_EXCEEDED` | Too many requests | Back off and retry after `Retry-After` |
| `INSUFFICIENT_CREDITS` | The account paying needs more credits | Add credits, or pay the call with x402 and retry |
| `PAYMENT_ALREADY_USED` | A payment was already bound to this gate or proof | Do not reuse payment evidence across checkouts |

## HTTP Status Codes

| Status | Meaning |
| - | - |
| 200 | Success |
| 202 | Accepted (async processing) |
| 400 | Bad request |
| 401 | Unauthorized |
| 402 | Payment required. The response carries a quote; add credits or pay the call with x402 and retry |
| 403 | Forbidden |
| 404 | Not found |
| 429 | Rate limited |
| 500 | Server error |

## Handling Errors

```javascript theme={"system"}
import { ProofableClient } from '@proofable/sdk';

const client = new ProofableClient();
const subjectAddress = '0x...';

try {
  const result = await client.gateCheck({
    gateId: 'gate_your-app-name',
    address: subjectAddress,
  });
  if (result.data?.gate?.allRequiredSatisfied !== true) {
    throw new Error('Required proof not found');
  }
} catch (error) {
  if (error.code === 'RATE_LIMIT_EXCEEDED') {
    // Back off and retry after Retry-After
  } else if (error.code === 'SIGNATURE_VERIFICATION_FAILED') {
    // Re-standardize and sign the current request
  }
  console.error(error.message);
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.