Reference

Errors

Every error returns a JSON body with a stable shape. Inspect the HTTP status code first, then branch on error.code.

Error envelope

error response

{
  "error": {
    "code": "invalid_request",
    "message": "business_name: Required"
  }
}

Codes returned today

Status	Code	Cause
400	invalid_request	Malformed JSON body, missing required field, or value failed validation (e.g. state is not 2 letters).
401	unauthorized	Missing Authorization header, malformed token, or key not found / revoked.
404	not_found	Resource (e.g. /business/{id}) does not exist. Note: a /verify call with no match returns 200 with status: 'not_found' — not a 404.
429	quota_exceeded	Monthly verification quota exceeded for this account. Upgrade the plan or wait until the next billing period. Overages are not enabled.
500	internal_error	Unhandled server-side failure. Safe to retry with exponential backoff.

This is the complete list of error codes the API emits today.

Retry strategy

4xx — do not retry without changing the request.
500 internal_error — retry with exponential backoff (e.g. 1s, 2s, 4s, 8s).
Network timeouts — retry idempotent calls (/search, /business/{id}, /verify) safely; all are read-only and side-effect free.

Handling example

javascript

const res = await fetch(url, { headers, method, body });

if (!res.ok) {
  const { error } = await res.json();
  switch (error.code) {
    case "unauthorized":
      throw new Error("Rotate or check TRUSTREGISTRY_KEY");
    case "invalid_request":
      throw new Error(`Bad input: ${error.message}`);
    case "internal_error":
      // retry with backoff
      break;
    default:
      throw new Error(`${error.code}: ${error.message}`);
  }
}