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

# Errors

> Error codes and responses for the NEUS API.

Responses use `code`, `message`, `type`. Fix the request, retry with backoff, or route to hosted verify.

## Error Response

```json theme={"dark"}
{
  "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`                |

## HTTP Status Codes

| Status | Meaning                     |
| ------ | --------------------------- |
| 200    | Success                     |
| 202    | Accepted (async processing) |
| 400    | Bad request                 |
| 401    | Unauthorized                |
| 403    | Forbidden                   |
| 404    | Not found                   |
| 429    | Rate limited                |
| 500    | Server error                |

## Handling Errors

```javascript theme={"dark"}
import { NeusClient } from '@neus/sdk';

const client = new NeusClient();
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 receipt 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);
}
```