Error codes

Error response format

All error responses follow this structure (request_id is included when available; quote it when contacting support):

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

Branch on code, never on message: the message is written for people and may be reworded. The retry fields described next are optional, and each is left out rather than guessed when the server does not know the answer.

Deciding whether to retry

retryable is decided per code (the Retry column below), and a few responses override their code where they know better: a 503 for a feature not enabled in this deployment is not retryable, and a 400 for downloading a job that is still running is.

What a repeat costs

On every route that accepts an Idempotency-Key, only a repeat of the same request with the key the first attempt carried is sure not to be charged again, and only while the route keeps that key, which is from 15 minutes to a year depending on the route and plan (below, and on each route's page), and for good on white-label credit allocation, whose key is kept with the move in your credit history. After that, the same key can start a new paid request. A key added only on the retry is a new request and does not cover the first attempt. Without a key, some routes treat an identical repeat as the same purchase for a while, and that window differs from route to route; after it, the repeat is a new purchase. Some routes that charge credits do not read the header at all, so a key protects nothing there and only their own terms apply: creating a monitor (below), the domain lookup in the OpenAPI document and inbox placement tests. The verification, batch, deliverability, activity and white-label pages and the OpenAPI document give these terms for their routes. The routes below have no page of their own.

Error code reference

These are the codes an integration is most likely to meet. It is not every code the API can send: account administration and the CRM integrations have codes of their own. The full list is the ErrorCode schema in the OpenAPI document.

Gateway timeouts

A request still running when its route’s time limit at the API gateway runs out is answered by the gateway, not by Kawaa, and so is one the gateway could not hand to the API at all. The limit is about 29 to 30 seconds on most routes, every route that charges credits included. Routes meant to answer quickly have less: 15 seconds on sign-in, registration and password recovery (/v1/auth/), GET /v1/account, the API key routes (/v1/api-keys), the invoice routes, checkout and the billing portal, the CRM connection routes, GET /v1/jobs, GET /v1/jobs/{id} and POST /v1/jobs/{id}/cancel; 10 seconds on sign-out and the tracking pixel and link routes; and 5 seconds on the health checks (GET /health). Either way the answer is a 503 whose whole body is:

{"message":"Service Unavailable"}

It has no success, error or request_id, so there is no code to branch on: read the status, and treat the missing envelope as the sign. It is not a 504. The request may still have run to the end, so retry with backoff, and on a route that charges credits only with the same Idempotency-Key. A 503 that does carry the envelope is Kawaa’s own and says in retryable whether waiting helps. The one 504 with a body is Kawaa’s own, from POST /v1/verify/free: GATEWAY_TIMEOUT with a job_id to send back.

The gateway answers two more failures itself, also without the envelope, and neither is run or charged: a request body over about 6 MB is a 413 whose whole body is {"message":"Request Entity Too Large"}, and a path with malformed percent-encoding (such as %E0%A4%A) is a 400 whose whole body is {"message":"Bad Request"}. An error whose body is not JSON at all (an HTML page) also comes from infrastructure in front of the API: handle it by its status.

Errors from the MCP endpoint

A tool call made through the MCP server is a REST call made with your key, so it can fail with any code above. The endpoint also answers three codes of its own before a message reaches the API. They arrive as a JSON-RPC error: the code is in error.data.code, the wait in error.data.retry_after_seconds, and the HTTP Retry-After header carries the same number. A tool call can also be refused inside the MCP server with codes the REST API does not use, such as UNKNOWN_ARGUMENT, INVALID_ARGUMENT and MAX_CREDITS_EXCEEDED. Those arrive as a failed tool result rather than a JSON-RPC error, and are listed on the MCP page.

Handling errors

Example: error handling in Node.js

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

Need help?

If you're experiencing persistent errors, check our status page for any ongoing issues, or contact support.