Skip to main content
Responses use 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

CodeMeaningWhat to do
INVALID_SIGNATURESignature verification failedRebuild the signing flow and retry
EXPIRED_SIGNATURESignature timestamp is too oldGenerate a fresh request and sign again
INVALID_WALLETWallet address format is invalidFix the request before retrying
VERIFIER_NOT_FOUNDRequested verifier does not existRead the live verifier catalog and correct the request
VERIFICATION_FAILEDThe requested check did not passTreat as a failed verification, not a transport error
PROOF_NOT_FOUNDId not foundConfirm the id and visibility
UNAUTHORIZEDThe caller is not allowed to perform this actionRe-authenticate the right owner or user
RATE_LIMITEDToo many requestsBack off and retry later

​
HTTP Status Codes

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

​
Handling Errors

try {
  const result = await client.verify({ ... });
} catch (error) {
  if (error.code === 'VERIFICATION_FAILED') {
    // The check did not pass
  } else if (error.code === 'RATE_LIMITED') {
    // Back off and retry later
  }
  console.error(error.message);
}