Error Handling HTTP Status Codes Status Meaning Your Action 200Success Process the response 204No Content (pull endpoint) Results still processing. Retry later. 400Bad Request Fix the request payload and resubmit 401Unauthorized Check your X-API-KEY header 403Forbidden Your API key does not have access to this project 404Not Found Invalid project hash, endpoint path, or expired pull token 429Rate Limited Back off and respect the Retry-After header 500Internal Server Error Retry with exponential backoff 503Service Unavailable Retry after 30 seconds
All errors return a consistent JSON structure:
{ "error" : "VALIDATION_ERROR" , "message" : "Missing required field: company_name" , "request_id" : "req-a1b2c3d4" }
Field Description errorMachine-readable error code. Use this for programmatic handling. messageHuman-readable description. Log it, but do not display to end users. request_idUnique identifier for the request. Include this in all support requests.
Always log request_id. It allows Zenoo support to trace the exact request through internal systems.
Error Codes Error Code HTTP Status Description VALIDATION_ERROR400 Missing or invalid required fields INVALID_JSON400 Request body is not valid JSON UNAUTHORIZED401 Missing or invalid API key FORBIDDEN403 API key lacks access to this project NOT_FOUND404 Invalid project hash or endpoint path TOKEN_EXPIRED404 Pull token has expired (30-day lifetime) RATE_LIMITED429 Too many requests. Check Retry-After header. INTERNAL_ERROR500 Unexpected server error PROVIDER_ERROR502 Upstream provider (registry, screening) returned an error SERVICE_UNAVAILABLE503 Service temporarily unavailable
Retry Strategy Exponential Backoff For transient errors (5xx, timeouts), retry with increasing delays:
Attempt 1: Immediate Attempt 2: Wait 5 seconds Attempt 3: Wait 25 seconds Attempt 4: Wait 60 seconds Maximum: 4 attempts
retry-client.js
retry_client.py
async function callWithRetry ( fn , maxRetries = 4 ) { const delays = [ 0 , 5000 , 25000 , 60000 ]; for ( let attempt = 0 ; attempt < maxRetries ; attempt ++ ) { try { const response = await fn (); if ( response . status === 429 ) { const retryAfter = response . headers . get ( "Retry-After" ); const delay = retryAfter ? parseInt ( retryAfter ) * 1000 : delays [ attempt ] * 2 ; await sleep ( delay ); continue ; } if ( response . status >= 500 ) { if ( attempt < maxRetries - 1 ) { await sleep ( delays [ attempt ]); continue ; } } return response ; } catch ( error ) { if ( attempt === maxRetries - 1 ) throw error ; await sleep ( delays [ attempt ]); } } } function sleep ( ms ) { return new Promise (( resolve ) => setTimeout ( resolve , ms )); }
When NOT to Retry Error Why 400 Bad RequestYour request is malformed. Fix the payload first. 401 UnauthorizedYour API key is wrong. Retrying will not fix it. 403 ForbiddenYour key lacks permissions. Contact Zenoo support. 404 Not FoundThe resource does not exist. Verify your endpoint URL and project hash.
Never retry 4xx errors automatically. They indicate a problem with your request, not a transient server issue.
Rate Limiting When you exceed your project’s rate limit, you receive a 429 response. The Retry-After header tells you how many seconds to wait. Always use this value instead of guessing.
{ "error" : "RATE_LIMITED" , "message" : "Rate limit exceeded. Retry after 60 seconds." , "request_id" : "req-a1b2c3d4" }
Handling rate limits:
Read the Retry-After header value.
Pause requests for that duration.
Resume. If you hit the limit again, increase your backoff.
For high-volume integrations, implement a request queue. Smooth out bursts rather than sending requests as fast as possible. Monitor your request rate and contact Zenoo if you need higher limits.
Zenoo Internal Error Classification Zenoo classifies errors from upstream providers into three categories. This determines automatic retry behavior on the server side.
Category Examples Retry Behavior Transient Timeouts, 5xx from providers Auto-retry with exponential backoff Permanent 4xx, invalid data, entity not found No retry. Check fails immediately. Rate Limited 429 from providers Extended backoff (2x multiplier)
Automatic Retry Schedule For async flows, Zenoo automatically retries transient provider failures on your behalf:
Retry Delay Cumulative Wait 1st 5 minutes 5 minutes 2nd 25 minutes 30 minutes 3rd 125 minutes ~2.5 hours
Maximum delay is capped at 240 minutes (4 hours). Rate-limited errors use a 2x multiplier on these delays.
After all retries are exhausted:
The check is marked as Failed.
A check.failed webhook is sent to your endpoint.
An API Failure alert is created in the case management system.
You do not need to implement retry logic for provider failures. Zenoo handles it automatically.
Circuit Breaker Zenoo protects upstream providers with a circuit breaker pattern:
State Behavior Closed Normal operation. Requests flow through to the provider. Open Provider is down. Requests fail fast and are queued for retry. Half-Open Recovery test. A single request is sent to check if the provider is back.
This is transparent to your integration. You do not need to implement any special handling. When a provider’s circuit breaker opens:
Checks for that provider are queued automatically.
Other providers continue operating normally.
You receive results via webhook once the provider recovers.
From your perspective, the verification simply takes longer to complete.
Timeout Handling Sync Requests If your X-SYNC-TIMEOUT is reached before all checks complete:
The response may contain partial results.
A pull token is included in the response headers for retrieving full results later.
Consider increasing the timeout or switching to async mode.
Async Requests The /init endpoint responds immediately with tokens, so connection timeouts are rare. If you experience them:
Check your network connectivity.
Verify the base URL and project hash.
Contact Zenoo support if the issue persists.
Monitoring Recommendations
Track error rates by endpoint and HTTP status code.Alert on 5xx spikes. Sustained 5xx errors may indicate a provider outage or Zenoo infrastructure issue.Monitor webhook delivery. Track delivery failures and retry rates.Log request_id for every API call. This is essential for debugging with Zenoo support.Track response times. Latency increases may indicate provider degradation.Monitor rate limit proximity. Alert when you reach 80% of your limit to avoid hitting it during traffic spikes.
Next Steps 
