> This page is part of the [Customer.io documentation](https://docs-customerio.netlify.app). For the complete index, see [llms.txt](https://docs-customerio.netlify.app/llms.txt).
> Last updated: February 27, 2026

# Common transactional API errors

Successful transactional requests return *200 OK*. If you get another response, something probably went wrong! This page can help you better understand and troubleshoot errors you receive from the transactional API.

## Successful requests[](#successful-requests)

A successful transactional API request returns a **200 OK** and looks like this:

```fallback
status: 200 OK
{
 "delivery_id": "A1C2E3jdieDks7zXdyz8XCFn1888",
 "queued_at": 1604977406
}
```

### status: 405 Method Not Allowed[](#status-405-method-not-allowed)

Possible misspelling of the request URI. The URI is `https://api.customer.io/v1/send/email` or `https://api.customer.io/v1/send/push`.

### status: 403 Forbidden[](#status-403-forbidden)

You probably need to take some additional steps to ensure that you’re authorized to send transactional messages.

Error Message

Resolution

Account owner’s email address is not confirmed.

Confirm your email address (or the email of the person who signed up for the Customer.io account) to send messages. Look for the confirmation email in the inbox that you used when signin-up, or [log in](https://fly.customer.io/login) to trigger another email confirmation.

Account is not yet approved for sending.

Verify your account to send messages. [Learn more about why we verify accounts](/journeys/account-verification).

Workspace is set to “Do Not Send.”

[Update your Workspace Settings](/journeys/workspaces) to send messages normally.

### status: 401 Unauthorized[](#status-401-unauthorized)

Invalid App API key. Check that your API key is correct and assigned to the correct workspace by visiting your [Account API Credentials page](https://fly-standalone.customer.io/settings/api_credentials?keyType=app). You may also have restricted your APP API keys to specific IP addresses.

### status: 400 Bad Request[](#status-400-bad-request)

An invalid request is typically caused by missing, malformed, or invalid data. See below for common errors and fixes.

Error Message

Resolution

Request entity must be JSON encoded and not exceed 2048 KB.

Check that your request is less than 2MB and is formatted correctly. Extra spaces, missing commas, and extra/missing quotation marks may all cause the request to fail.

“from” address domain has not been verified.

[Verify your domain](/journeys/authentication) to send a message using the specified “from” address.

“transactional\_message\_id” not found.

Check that you’re using a valid `transactional_message_id` in your workspace.

Missing required field

“to” and “identifiers” are required fields. “from”, “subject”, and “body” are not required when using a `transactional_message_id` in your request and the message template has these values.

Invalid email address in field

Email addresses in “to”, “from”, “bcc”, and “reply-to” must be properly formatted. Use angled brackets and quote the “name” portion of an email address like `"\"Name\" <test@example.com>"` to add a display name to an email address and avoid problems that might arise from special characters. Use commas to separate multiple email addresses.

Limit of 15 recipients exceeded.

A single request can have up to 15 recipients across both “to” and “bcc” fields.

Invalid format in field “message\_data”

Check that the “message\_data” is formatted correctly. Extra spaces, missing commas, and extra/missing quotation marks may cause the request to fail.

“Header” is a reserved header.

Reserved headers cannot be overwritten. See the [full list of denylisted headers](/journeys/custom-mail-headers/#denylisted-headers).

Custom headers must be strings and not contain any non-ASCII characters.

Headers must be comma-separated and consist of only ASCII characters.

Missing filename or content for attachment.

Every attachment must have a filename and corresponding base64-encoded content.

Forbidden file type

We support a limited set of file types as attachments. [See full list of supported file types](/journeys/transactional-faq/#what-attachment-file-types-are-forbidden).

Attachment must be base64-encoded

Attachments must be base64-encoded. See examples here.

Total attachment size exceeds 2048KB limit.

Total attachments cannot exceed 2MB in size.

Invalid custom\_payload or custom\_data format.

The value in the iOS and/or Android `custom_payload` and `custom_data` fields must be a string.

### View in Browser links do not work[](#view-in-browser-links-do-not-work)

“View in browser” links do not work with Transactional messages that have *Protect sensitive data* enabled. We don’t retain protected messages, and cannot retrieve them.

### Need help?[](#need-help)

If you’ve encountered a different error, or need more help fixing one of these, please [let us know](http://win@customer.io)!