Error codes

The BosonMail SDK surfaces errors in two ways: constructor validation throws synchronously, and method calls resolve with success: false results. This page catalogs every known error, its source, and how to fix it.

Constructor errors (thrown)

The constructor is the only place the SDK throws. All other failures resolve gracefully.

Error message	Trigger	Fix
`'apiKey' must be a non-empty string`	`apiKey` is missing, empty, or whitespace-only after trim.	Set `BOSONMAIL_API_KEY` in the environment and validate it before constructing the client.
`'timeoutMs' must be a positive number`	`timeoutMs` is not a finite number greater than 0.	Pass a positive integer, or omit to use the 30,000 ms default.
`'baseUrl' must be a non-empty URL`	`baseUrl` is empty after trim.	Provide a valid URL string, or omit to use the default.
`'baseUrl' must be an absolute HTTP(S) URL`	`baseUrl` does not start with `http://` or `https://`.	Use an absolute URL such as `https://webmail.bosonware.com/api/v1`.

sendEmail client-side validation

These errors return { success: false, errorMessage } with no statusCode. No request is sent.

Error message	Trigger	Fix
`'to' must contain at least one recipient`	`to` is empty, not a string, or an array with empty/whitespace elements.	Provide at least one valid recipient string.
`'subject' must be a non-empty string`	`subject` is missing or empty after trim.	Provide a non-empty subject line.
`'body' must be an object`	The third argument is not an object.	Pass an object with `text`, `html`, `cc`, `bcc`, and/or `attachments`.
`'text' and 'html' must be strings`	`text` or `html` is defined but not a string.	Pass strings, or omit the field.
`Email must contain text or HTML content`	Neither `text` nor `html` is a non-empty string after trim.	Provide at least one of `text` or `html`.
`'attachments' must be an array`	`attachments` is defined but not an array.	Pass an array of `SendAttachment` objects, or omit the field.
`A maximum of 10 attachments is allowed`	More than 10 attachments provided.	Reduce to 10 or fewer.
`Each attachment must have a filename`	An attachment object is missing `filename`.	Add a `filename` string to every attachment.
`Invalid content for attachment "<filename>"`	Attachment `content` is not a `Blob`, `ArrayBuffer`, or `Uint8Array`.	Convert the content to a `Buffer`, `Uint8Array`, or `Blob`. Strings and streams are not accepted.
`Attachment "<filename>" exceeds the 10 MB per-attachment limit`	Attachment larger than 10,485,760 bytes.	Compress or split the file.
`Total attachment size exceeds the 20 MB limit`	Cumulative attachment size exceeds 20,971,520 bytes.	Reduce total payload size.
`Failed to prepare email: <message>`	An unexpected exception while building the request body.	Review attachment content and types; contact support if reproducible.

sendEmail API and network errors

These errors return { success: false, statusCode?, errorMessage } after a request is attempted.

Error pattern	Trigger	Fix
`Request failed (HTTP <status> <statusText>)`	The API returned a non-OK status and no parseable error detail.	Check the HTTP status: 4xx usually means a client error, 5xx means a server problem.
`body.error` (string)	The API returned an error string in the response body.	Read the message and correct the request.
`body.error.message`	The API returned an error object with a message field.	Same as above.
`body.message`	The API returned a top-level message field.	Same as above.
`Request timed out after <timeoutMs>ms. The outcome may be unknown; check email status before retrying.`	The request exceeded `timeoutMs`.	Check `getEmailStatus` with the message ID if you have one, or log for manual review before retrying.

getEmailStatus errors

These errors return EmailStatusResult with success: false.

`errorCode`	Source	Meaning	Fix
`invalid_id`	SDK	`messageId` is empty or not a string.	Pass a non-empty string identifier.
`request_failed`	SDK	Network error or timeout during the status request.	Retry after a short delay; check connectivity.
`invalid_response`	SDK	The API response is missing required fields (`id`, `status`, or `delivery_status`).	Report to support@bosonware.com with the message ID and timestamp.
`unauthorized`	API	Authentication missing or invalid.	Verify the API key is correct and has not been revoked.
`not_found`	API	The email could not be found for the given message ID.	Confirm the message ID; it may be too old or from a different account.
`http_<status>`	SDK fallback	The API returned a non-OK status without a recognized error code.	Treat as a server or client error based on the HTTP status range.

HTTP status interpretation

Use these general rules when the SDK returns a statusCode:

Range	Meaning	Action
400-499	Client error	Review request parameters, authentication, and payload size. Do not blindly retry.
500-599	Server error	Retry with backoff. If persistent, contact support.

BosonWare has not published the exact HTTP statuses for specific API errors. The ranges above are general guidance.

Next steps

Troubleshooting

Step-by-step fixes for common errors and runtime issues.

Request and response formats

How the SDK parses errors and maps them to Result fields.

API reference

Endpoint details and curl examples for direct API calls.

Security best practices

Protect API keys and prevent credential leaks.

Getting Started

SDK Reference

Guides

Advanced

Resources

Constructor errors (thrown)

sendEmail client-side validation

sendEmail API and network errors

getEmailStatus errors

HTTP status interpretation

Next steps

Troubleshooting

Request and response formats

API reference

Security best practices

​Constructor errors (thrown)

​sendEmail client-side validation

​sendEmail API and network errors

​getEmailStatus errors

​HTTP status interpretation

​Next steps

Troubleshooting

Request and response formats

API reference

Security best practices

Constructor errors (thrown)

sendEmail client-side validation

sendEmail API and network errors

getEmailStatus errors

HTTP status interpretation

Next steps