Errors

Why auth failures return 404, not 401/403

MailInsightX deliberately returns 404 Not Found for almost every authentication failure across the entire platform, not just this API - a missing, invalid, or wrong-type API key, an inactive key, or a JWT-authenticated request that isn't an API key at all. This is intentional: it avoids confirming to an unauthenticated caller that a given route even exists. If you're getting a plain 404 with no JSON body, check your authentication first before assuming the endpoint is wrong.

Two authentication-related failures are the deliberate exceptions, and do return a real status with a JSON body, because by that point the caller has already proven they hold a valid key for a real account:

Status	Code	Meaning
403	PLAN_UPGRADE_REQUIRED	Your account's plan doesn't include API access (Free plan).
404	ACCOUNT_SUSPENDED	Your account is currently suspended. See Account Suspension & Restrictions.

Common status codes

Status	Meaning
200	Success.
400	Invalid request - bad input, a validation failure, or (for /v1/verify) a domain with no valid MX record.
402	Insufficient credits for the operation.
404	Authentication failure (see above), or a resource genuinely not found.
429	Rate limit exceeded - see Rate Limits.
500	An internal error occurred.
502	A downstream verification step failed (see POST /v1/verify).

Every endpoint's own page documents its specific error responses in full - this page covers only the errors common to the whole API.