REST API · v1

Errors and limits

Non-2xx responses use the same metadata envelope as successful requests. Log the error code and X-Request-ID response header when diagnosing failures.

Error shape

json

{
  "success": false,
  "error": {
    "code": "INVALID_EMAIL",
    "message": "Invalid email format"
  },
  "meta": {
    "requestId": "req_example",
    "duration": 2,
    "version": "v1"
  }
}

Common codes

HTTP	Code	Meaning
400	`INVALID_JSON`	The body is not valid JSON.
400	`INVALID_EMAIL`	The supplied email format is invalid.
400	`MISSING_EMAILS`	The bulk emails array is missing.
400	`TOO_MANY_EMAILS`	A bulk request contains more than 1,000 values.
400	`MISSING_DOMAIN`	Finder received neither domain nor companyName.
401	`UNAUTHORIZED`	The bearer token is missing or invalid.
429	`RATE_LIMITED`	The current key or IP exceeded its request window.
502	`BACKEND_ERROR`	The Reacher verification service returned an error.
500	`INTERNAL_ERROR`	An unexpected server error occurred.

Current limits

100 requests per 60-second window for non-master keys or anonymous development traffic.
The configured master key bypasses the in-memory rate limiter.
Bulk verification accepts at most 1,000 input values per synchronous request.
Rate-limit state is process-local in this release and must be replaced before horizontal scaling.