Error codes

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error description",
    "request_id": "abc123...",
    "retryable": false
  }
}

{"message":"Service Unavailable"}

// Node.js 20 or later, where fetch and crypto are globals.
// One key per logical request, reused on every retry of it:
// POST /v1/verify charges, and the key is what stops a retry paying twice.
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function verifyEmail(email, idempotencyKey = crypto.randomUUID(), attempt = 1) {
  const response = await fetch('https://api.kawaa.com/v1/verify', {
    method: 'POST',
    headers: {
      'X-Api-Key': process.env.KAWAA_API_KEY,
      'Content-Type': 'application/json',
      'Idempotency-Key': idempotencyKey,
    },
    body: JSON.stringify({ email }),
  });

  // A gateway timeout or outage answers before Kawaa does: no { success, error }
  // envelope, and sometimes not JSON at all.
  const data = await response.json().catch(() => null);
  if (response.ok && data?.success) return data.data;

  const error = data?.error ?? {
    code: 'HTTP_' + response.status,
    message: response.statusText || 'No error body',
    // Without an envelope, only a 5xx or a 429 can succeed on a retry. The
    // same Idempotency-Key makes retrying a 5xx safe on this charging route.
    retryable: response.status >= 500 || response.status === 429,
  };
  const { code, message, retryable, retry_after_seconds } = error;

  if (code === 'INSUFFICIENT_CREDITS') {
    throw new Error('Please add credits to continue');
  }
  if (code === 'BAD_REQUEST') {
    // e.g. malformed email input: skip it
    return { status: 'skipped', reason: message };
  }

  // Only retry what the API says can succeed. An absent retryable means
  // "it depends", so do not loop on it.
  if (retryable === true && attempt < 4) {
    // The server's wait when it gives one (body or Retry-After header),
    // otherwise exponential backoff.
    const retryAfter = retry_after_seconds ?? Number(response.headers.get('Retry-After'));
    const waitSeconds = retryAfter > 0 ? retryAfter : 2 ** attempt;
    await sleep(waitSeconds * 1000);
    return verifyEmail(email, idempotencyKey, attempt + 1);
  }

  throw new Error(code + ': ' + message);
}