code, message, type. Fix the request, retry with backoff, or route to hosted verify.
Error Response
{
"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
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);
}