Error Codes

Mailzeno provides structured errors at every layer — the SDK, the REST API, and the core SMTP engine. All errors return a consistent JSON response.

Error response format

All error responses follow a consistent structure:

Error Response

{
"error": "Human readable error message",
"code": "error_code_string"
}

Field	Type	Description
`error`	string	Human-readable error description
`code`	string	Machine-readable error code

API error codes

Status	Code	Description
`400`	`missing_required_fields`	`smtpId`, `from`, or `to` is missing
`400`	`missing_email_content`	No subject/html and no template specified
`401`	`invalid_auth_header`	Missing or malformed Authorization header
`401`	`invalid_api_key`	API key is invalid or has been deactivated
`429`	`rate_limit_exceeded`	Too many requests (check `retry-after` header)
`500`	`profile_not_found`	User profile could not be located
`500`	`email_send_failed`	SMTP sending failed
`500`	`internal_server_error`	Unexpected server error

Core engine error codes

The @mailzeno/core SMTP engine provides specific error classes for SMTP-level failures:

Code	Class	Description
`VALIDATION_ERROR`	`ValidationError`	Invalid input (missing from, to, or subject)
`RENDER_ERROR`	`RenderError`	React email rendering failed
`SMTP_CONNECTION_ERROR`	`SMTPConnectionError`	Could not connect to SMTP server
`SMTP_AUTH_ERROR`	`SMTPAuthError`	SMTP authentication failed (wrong credentials)
`SMTP_RESPONSE_ERROR`	`SMTPResponseError`	SMTP server returned an error
`SMTP_TIMEOUT_ERROR`	`SMTPTimeoutError`	SMTP connection timed out
`UNKNOWN_ERROR`	`MailzenoError`	Unexpected error (base class)

SDK error handling

The SDK throws MailzenoError with HTTP status, error code, and request ID:

import { MailZeno } from "@mailzeno/client"

try {
await mz.emails.send(payload)
} catch (err) {
console.error("Message:", err.message)
console.error("Status:", err.status)       // e.g. 401, 429, 500
console.error("Code:", err.code)           // e.g. "invalid_api_key"
console.error("Request ID:", err.requestId) // x-request-id header
}

Error examples

Missing fields

400 Bad Request

{
"error": "Missing required fields: smtpId, from, to",
"code": "missing_required_fields"
}

Authentication error

401 Unauthorized

{
"error": "Invalid or missing API key",
"code": "invalid_api_key"
}

Rate limit error

429 Too Many Requests

{
"error": "Rate limit exceeded",
"code": "rate_limit_exceeded"
}

Server error

500 Internal Server Error

{
"error": "Email sending failed",
"code": "email_send_failed"
}