Errors

Mailbeam uses standard HTTP status codes. All error responses include a machine-readable error field and a human-readable message.

Error response structure

{
  "error": "invalid_email_format",
  "message": "The email address is not RFC 5322 compliant.",
  "request_id": "req_01hx9abc123"
}

Always check the error field in your code — message may change; error is stable.

HTTP status codes

Code	Meaning
`200`	Request succeeded
`400`	Bad request — check your payload
`401`	Authentication failed
`403`	Forbidden — insufficient permissions
`422`	Validation error — email address has a specific issue
`429`	Rate limit or quota exceeded
`500`	Internal server error — contact support

Error codes

Authentication errors

Error	Status	Description
`missing_api_key`	401	No Authorization header
`invalid_api_key`	401	Key format is invalid
`revoked_api_key`	401	Key has been revoked
`insufficient_permissions`	403	Key lacks required scope

Validation errors

Error	Status	Description
`invalid_email_format`	422	Email fails RFC 5322 syntax
`email_too_long`	422	Email exceeds 254 characters
`missing_required_field`	400	`email` field not present in body
`invalid_json`	400	Request body is not valid JSON

Rate limit errors

Error	Status	Description
`rate_limit_exceeded`	429	Per-second limit hit; check `retry_after`
`quota_exceeded`	429	Monthly quota exhausted (Free plan blocks; paid plans continue with overage billing)

Server errors

Error	Status	Description
`internal_error`	500	Transient server error — retry with backoff
`upstream_timeout`	504	SMTP probe timed out; result is inconclusive

Handling errors in code

try {
  const result = await mb.verify(email);
  if (!result.valid) {
    // Email is invalid but request succeeded — this is NOT an error
    handleInvalidEmail(result.reason);
  }
} catch (err) {
  switch (err.code) {
    case "rate_limit_exceeded":
      await sleep(err.retryAfter * 1000);
      // retry
      break;
    case "quota_exceeded":
      // Notify ops, switch to fallback, or allow signup
      notifyOpsTeam();
      break;
    case "invalid_api_key":
    case "revoked_api_key":
      // Alert — configuration issue
      alertPagerDuty("Mailbeam API key invalid");
      break;
    default:
      // Log and continue — don't block users on unexpected errors
      logger.error("Mailbeam error", { code: err.code, requestId: err.requestId });
  }
}

The `reason` field

When valid is false, the reason field contains a machine-readable string explaining why:

Reason	Explanation
`invalid_syntax`	Fails RFC 5322 format check
`no_mx_records`	Domain has no mail servers
`smtp_rejected`	Mailbox does not exist
`disposable_domain`	Matched a temporary email provider
`role_address`	Looks like a non-personal address
`catch_all_unverifiable`	Domain accepts all mail; SMTP is inconclusive
`timeout`	SMTP probe timed out — treat as unknown

Never block users solely on catch_all_unverifiable. Use the score field instead to make nuanced decisions.