​

Error Handling

​

HTTP Status Codes

​

Error Response Format

{
  "error": "VALIDATION_ERROR",
  "message": "Missing required field: company_name",
  "request_id": "req-a1b2c3d4"
}

​

Error Codes

​

Retry Strategy

​

Exponential Backoff

Attempt 1: Immediate
Attempt 2: Wait 5 seconds
Attempt 3: Wait 25 seconds
Attempt 4: Wait 60 seconds
Maximum: 4 attempts

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));
}

import time
import requests
from requests.exceptions import RequestException

def call_with_retry(fn, max_retries=4):
    delays = [0, 5, 25, 60]

    for attempt in range(max_retries):
        try:
            response = fn()

            if response.status_code == 429:
                retry_after = response.headers.get('Retry-After')
                delay = int(retry_after) if retry_after else delays[attempt] * 2
                time.sleep(delay)
                continue

            if response.status_code >= 500:
                if attempt < max_retries - 1:
                    time.sleep(delays[attempt])
                    continue

            return response
        except RequestException:
            if attempt == max_retries - 1:
                raise
            time.sleep(delays[attempt])

​

When NOT to Retry

​

Rate Limiting

{
  "error": "RATE_LIMITED",
  "message": "Rate limit exceeded. Retry after 60 seconds.",
  "request_id": "req-a1b2c3d4"
}

1. Read the Retry-After header value.
2. Pause requests for that duration.
3. Resume. If you hit the limit again, increase your backoff.

​

Zenoo Internal Error Classification

​

Automatic Retry Schedule

• 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.

​

Circuit Breaker

• Checks for that provider are queued automatically.
• Other providers continue operating normally.
• You receive results via webhook once the provider recovers.

​

Timeout Handling

​

Sync Requests

• 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

• Check your network connectivity.
• Verify the base URL and project hash.
• Contact Zenoo support if the issue persists.

​

Monitoring Recommendations

1. Track error rates by endpoint and HTTP status code.
2. Alert on 5xx spikes. Sustained 5xx errors may indicate a provider outage or Zenoo infrastructure issue.
3. Monitor webhook delivery. Track delivery failures and retry rates.
4. Log request_id for every API call. This is essential for debugging with Zenoo support.
5. Track response times. Latency increases may indicate provider degradation.
6. Monitor rate limit proximity. Alert when you reach 80% of your limit to avoid hitting it during traffic spikes.

​

Next Steps

• Webhooks — Handle webhook delivery failures and retries
• Idempotency — Prevent duplicate verifications
• Result Delivery — Choose between push, pull, and ping+pull
• Testing & Sandbox — Test error scenarios in staging