> ## Documentation Index > Fetch the complete documentation index at: https://docs.bosonware.com/llms.txt > Use this file to discover all available pages before exploring further. # Error codes > Complete catalog of BosonMail SDK error codes and messages: constructor throws, client-side validation, API responses, and network failures. 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 ""` | 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 "" 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: ` | 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 )` | 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 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](mailto: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_` | 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. | > [!NOTE] > > BosonWare has not published the exact HTTP statuses for specific API errors. The ranges above are general guidance. ## Next steps > [card] [Troubleshooting](https://docs.bosonware.com/advanced/troubleshooting.md) > > Step-by-step fixes for common errors and runtime issues. > [card] [Request and response formats](https://docs.bosonware.com/advanced/request-response-formats.md) > > How the SDK parses errors and maps them to Result fields. > [card] [API reference](https://docs.bosonware.com/advanced/api-reference.md) > > Endpoint details and curl examples for direct API calls. > [card] [Security best practices](https://docs.bosonware.com/advanced/security.md) > > Protect API keys and prevent credential leaks. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.