Errors

Handle validation, authentication, quota, and service errors.

Non-2xx responses use a stable error envelope:

{
  "success": false,
  "request_id": "fd3279e1-5657-466d-b98b-d9e7627e0788",
  "status": "failed",
  "risk_level": "unknown",
  "recommended_action": "flag",
  "decision_source": "signupbear_policy",
  "policy_version": "2026-07-beta-1",
  "checked_at": "2026-07-28T08:40:00.000Z",
  "processing_ms": 2,
  "error": {
    "code": "INVALID_INPUT",
    "message": "Provide at least one of 'email' or 'ip'"
  }
}

Error codes

HTTP	Code	Meaning
400	INVALID_JSON	Request body is not valid JSON
400	INVALID_INPUT	A required field is missing or invalid
401	UNAUTHORIZED	Bearer authorization is missing or malformed
401	INVALID_API_KEY	API key is unknown, invalid, or revoked
429	MONTHLY_LIMIT_EXCEEDED	Current plan limit has been reached
500	INTERNAL_ERROR	SignupBear could not complete the check

Retry guidance

• Do not retry HTTP 400 or 401 without changing the request or key.
• Wait for a new usage period or a plan change after HTTP 429.
• Retry HTTP 500 only with bounded exponential backoff.
• Always log request_id; never log the API key.