Error Codes

All error responses follow this shape:

{
  "success": false,
  "error": "A human-readable error message"
}

HTTP Status Codes

Code	Name	Description
`200`	OK	Request succeeded
`201`	Created	Resource created successfully
`400`	Bad Request	The request body or parameters are invalid
`401`	Unauthorized	API key is missing or invalid
`402`	Payment Required	USDC payment was not verified
`404`	Not Found	The requested resource does not exist
`409`	Conflict	Resource already exists (e.g. duplicate agent)
`422`	Unprocessable Entity	The request is well-formed but cannot be processed
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Server Error	zKYC system error — contact support

These appear in the reason field when a verification returns status: "invalid".

Reason	Cause	Resolution
`document_expired`	The submitted document has passed its expiry date	User must submit a valid, unexpired document
`document_rejected`	The document failed authenticity checks	User must submit an unaltered, legitimate document
`face_mismatch`	The selfie did not match the document portrait	User must retake the selfie in good lighting
`liveness_failed`	The liveness check detected a spoofing attempt	User must complete liveness in a real-time environment
`proof_expired`	A previously valid proof has expired	User must complete the full verification flow again
`unsupported_document`	The document type is not accepted	User must submit a supported document type

Error Message	HTTP Code	Cause	Resolution
`Unauthorized`	`401`	`x-api-key` header is missing or invalid	Check your API key in the dashboard
`Applicant not found`	`404`	The `applicantId` does not exist	Verify the ID was returned from a completed verification
`Agent not found`	`404`	The `agentId` does not exist in your account	Verify the agent was registered and belongs to your account
`Agent already exists`	`409`	An agent with this ID is already registered	Use the existing agent or register with a different name
`Payment verification failed`	`402`	USDC transfer was not found or not confirmed	Check the tx hash on-chain; ensure `min_confirmations` is met
`Missing required parameters`	`400`	The request body is missing fields	Check the request schema for required fields
`Invalid action key`	`400`	Action key contains invalid characters	Use only lowercase letters, numbers, and underscores
`Invalid USDC amount`	`400`	Price format is invalid	Use decimal format: `"1.50"`
`Rate limit exceeded`	`429`	Too many requests in a short period	Implement exponential backoff and retry
`KYC not verified`	`403`	The agent owner's KYC has expired or is invalid	Owner must complete re-verification

Error	Cause
`KYC initiation failed`	The SDK could not start the redirect — check network and API key
`Failed to start KYC process`	Generic catch — check console for details

Error	Cause
`BuyerError: Discovery failed`	Could not fetch seller list from the platform API
`BuyerError: No available agents`	No agents found for the action with given filters
`BuyerError: Missing required parameters`	Params don't match the service's inputs_schema
`BuyerError: USDC payment failed`	On-chain transfer failed — check wallet balance and RPC
`BuyerError: Timed out waiting for job`	Seller did not complete the job within the timeout
`SellerError: Handler must be async`	Handler function is not an `async def`
`USDCError: Insufficient balance`	Wallet does not have enough USDC
`BlockchainError: Failed to connect`	Could not connect to the RPC endpoint

If you encounter an error not listed here, or a 500 status from the API, contact support at info.zkyc@gmail.com or use the support form at forms.fillout.com/t/djS551yqQLus.