Troubleshooting

Use this page when a request fails, data doesn’t appear, or Iterable setup stops at a step. Find the symptom or the exact message you see, then apply the fix. Each entry gives the cause and the fix in a few lines, with links to the full guide.

Before you begin

• Check the environment. The account menu at the bottom of the left sidebar shows your name over <Organization> / <Environment>. Customer profiles, events, integrations, and API keys each belong to one environment, so a working setup looks empty from another environment.
• Keep the evidence. Note the HTTP status, the full response body, the messageId, and the time of the request with its time zone. You need them for most fixes and when you contact your JustAI team.

Customer data APIs

These entries cover the Identify API, the Track API, and the Profiles API at https://ingest.justwords.ai.

Every request returns 404 Not Found

Cause: The method or path doesn’t match an endpoint exactly. A trailing slash, a GET to Identify or Track, or a path such as /v1/batch returns 404 with the plain-text body 404 Not Found.

Fix: Use one of these three endpoints, with no trailing slash:

POST https://ingest.justwords.ai/api/identify/{org_slug}
POST https://ingest.justwords.ai/api/track/{org_slug}
GET https://ingest.justwords.ai/api/profiles/{org_slug}/{user_id}

400 with {"error":"Invalid org slug"}

Cause: The organization slug or path value in the path has the wrong format. Any uppercase letter fails. Organization slug lists the format rules.

Fix: Copy the organization slug your JustAI team gave you. In the Production environment, it also appears inside the system webhook and content data feed URLs on your Iterable connection in Settings > Integrations. For another environment, use the path value your JustAI team gave you.

400 with {"error":"Invalid environment"}

Cause: The X-JustAI-Environment header is empty or has a value in the wrong format, such as Prod.

Fix: For production, remove the header or send prod. For another environment, send the environment key your JustAI team gave you. Don’t add an empty environment header in a source tool.

401 with {"error":"Missing API key"}

Cause: The request has no API key.

Fix: Send the key in an X-Api-Key header. Check that your tool adds the header to every request, not only to its test request.

401 with {"error":"Invalid API key"}

Cause: JustAI doesn’t recognize the key. The key is incomplete, revoked, or still a placeholder. When the request has a non-blank X-Api-Key header, JustAI checks only that header and ignores any Authorization header.

Fix: Open Settings > API keys in the environment you send to. Compare the last five characters of your key with the Suffix column, and check that Status reads active. A new key may not work immediately. Confirm it succeeds before switching traffic to it. If you lost the key, create a new one, because JustAI shows each key only once.

403 with {"error":"Forbidden"}

Cause: The key doesn’t match the request. One of these is true:

• The key belongs to another organization.
• The key belongs to a different environment than the path or the X-JustAI-Environment header.
• The request has no environment header, which selects production, but the key belongs to another environment.
• The header is production. Production accepts only prod.
• The environment was removed.

Fix: Create the key while the target environment is selected. The API keys page names the environment at the top. For production, use your organization slug in the path and omit the environment header. For another environment, use that environment’s path value and its X-JustAI-Environment value. Your JustAI team gives you both.

Identify returns 400 with “At least one trait is required unless consent is provided”

Cause: The body has no top-level traits object with at least one key. JustAI ignores context.traits. RudderStack sends Identify traits in context.traits. Segment sends an empty traits object for an identify call made without traits.

Fix: Send traits in the top-level traits object. For RudderStack, add the transformation in the RudderStack guide, which copies context.traits into traits. Identify calls with no traits at all fail by design. Filter them out or ignore the failures.

Identify returns 400 with “Expected string, received null” or “Required” at userId

Cause: The call is anonymous. Identify needs a non-empty string userId. A number fails with “Expected string, received number”.

Fix: Send only identified calls to Identify. In Segment, add a trigger condition that the user ID exists. In RudderStack, drop calls with an empty userId in the transformation. Send numeric IDs as strings.

400 with “Expected object, received array”

Cause: Your tool sent a JSON array, which means batching is on. A {"batch": [...]} body fails too. Track returns {"error":"Invalid literal value, expected \"track\""} for it, and Identify reports “Required” at userId. On Track, the same message also appears when properties is an array.

Fix: Send one JSON object per request. Turn off Enable Batching? in Segment. In Hightouch, send a single row per request. On Track, send properties as an object.

400 with “Invalid datetime” or “Expected string, received number”

Cause: The timestamp isn’t an ISO 8601 string with a time zone. Common causes are a time with no time zone, a space in place of T, a date with no time, and an epoch number. Track returns the message as {"error":"Invalid datetime"}. Identify lists it in issues. Track also returns “Expected string, received number” when userId or messageId is a number.

Fix: Send 2026-10-01T12:00:00Z, or a numeric offset such as 2026-10-01T17:30:00+05:30. In a warehouse, format the timestamp as text in SQL before you sync it. Send IDs as strings. Identify timestamps lists every accepted and rejected form.

Identify returns 400 with “timestamp cannot be more than 5 minutes in the future”

Cause: The timestamp is more than five minutes later than JustAI’s clock.

Fix: Send the time of the change in UTC, and check the clock and time zone conversion in your source. You can also omit timestamp. JustAI then uses the time it receives the call.

Track returns another 400 message

Track returns only the first problem it finds, without the field name. Find the body in the Track API error table, fix that problem, send again, and check the next response.

Identify returns 409 with “messageId … was already used for a different call”

Cause: You reused a messageId with a different userId, timestamp, or traits. This happens in warehouse syncs that build the ID from the user ID and updated_at when a trait changes but updated_at doesn’t.

Fix: Use a new messageId for every new update. Reuse an ID only to retry the identical call. In Hightouch, add every trait column to message_key, or leave messageId out of the Identify template. See the Hightouch guide.

Identify returns 200 with "duplicate":true and nothing changes

Cause: JustAI already accepted this messageId with the same userId, timestamp, and traits. It doesn’t apply the call again, and it ignores any changed consent in the retry.

Fix: Send each new update, including a consent change, with a new messageId.

Identify returns 200 but a trait keeps its old value

Cause: One of these is true:

• The profile has a newer value for that trait. Each trait keeps its own update time, and a call with an older timestamp doesn’t overwrite it.
• You sent null. JustAI stores null. It doesn’t remove the trait.
• You sent part of a nested object. A nested object or array replaces the whole stored value.
• You read the profile right after the update. A read can briefly return the previous values.

Fix: Wait a minute and read the profile again. Check the timestamp you send, and send the complete nested object. See Send customer profiles.

Profiles API returns 404 with {"error":"Profile not found"}

Cause: No profile has that user ID in this environment. The Profiles API looks people up by user ID only, never by email, so people added by CSV upload without a user_id column can’t be read. A profile created moments ago can also read as not found briefly.

Fix: URL-encode the user ID in the path. For example, / becomes %2F and @ becomes %40. Check that you send to the same environment as your Identify calls. If you sent the Identify call moments ago, wait a minute and read again. To find a person by email, search for them on Users.

Track returns 413 with {"error":"Track event is too large"}

Cause: The event is over the size limit of about 1 MB. JustAI counts a larger size than your request body.

Fix: Remove large values from properties and context. Keep events that start or move journeys under 128 KB. JustAI accepts and counts an event between 128 KB and the 1 MB limit, but that event can’t start or move a journey.

503 with {"error":"Event storage is unavailable"} or 500 with {"error":"Internal error"}

Cause: A temporary problem on the JustAI side.

Fix: Retry with exponential backoff and jitter. Send the same body and the same messageId, so JustAI counts the event once. See Errors and retries.

New key shows “API key creation is restricted for this environment. Ask an organization admin for help.”

Cause: API access isn’t enabled for your organization. Admins in your organization can’t turn it on.

Fix: Ask your JustAI team to enable API access. After that, any member of your organization can create keys.

An event doesn’t appear in Events > Custom events

Cause: One of these is true:

• The event is still processing. New events can take time to appear.
• You’re viewing a different environment from the one you sent to.
• The event last arrived more than 30 days ago. The list hides older events by default.
• JustAI didn’t accept the request. Track returns 202 only for accepted events.

Fix: Confirm the 202 response and the environment, then select Refresh. For older events, open the filter and select Include inactive. If an accepted event still doesn’t appear after you refresh, contact your JustAI team with its messageId.

The journey event picker says “No events have arrived yet.” or doesn’t list your event

Cause: The picker lists only event names that JustAI received in this environment in the last 30 days.

Fix: Send one test event with the exact name through the Track API. When it appears in Events > Custom events, build the journey.

An event was accepted, but the journey didn’t start

Cause: One of these is true:

• The journey isn’t published, or the event arrived before you published it.
• The event name differs from the journey’s event, even in case. Order Completed and order completed are different events.
• The event has no userId. Events with only an anonymousId never reach journeys.
• An Only when condition compares different types. The text "14" doesn’t match the number 14.
• The event is larger than 128 KB.

Fix: Correct the problem. After you publish a journey, wait about a minute before you send a test event. Events that arrive in the first moments after publishing can miss the journey. Then send a new event with a new messageId. Journey triggers don’t wait for the Custom events delay.

To check for the run, open the journey from Journeys. A published journey opens on its Live view, with Recent runs beside it. Enter the user ID in Email or user ID, press Enter, and select the run to see each step it reached. To trace the event itself, see Confirm that an event reaches a journey.

A journey run started, but the email wasn’t sent

Cause: The person has no email address. A Track event can start a run for a userId that has no profile, and JustAI sends Iterable email to the email trait on the profile.

Fix: Send an Identify call with traits.email before the events that start email journeys. Use the same user ID in both, with no extra spaces. See Identity and consent.

Data sources

Profiles pick up company or account traits

Cause: Your source sends Group calls to the Identify endpoint. Identify doesn’t check the call type, so JustAI writes the group’s traits onto the person’s profile.

Fix: Filter by call type. Send only identify calls to Identify and only track calls to Track. In Segment, use Webhooks (Actions) with an event-type trigger on each mapping. Don’t use Webhooks (Classic), which sends every call to every URL. In RudderStack, drop other call types in the transformation.

Segment or RudderStack reports failed deliveries

Cause: JustAI rejected the events with a 4xx response. Segment reports the failed deliveries for the destination. RudderStack shows them in the destination’s Live Events tab, where you select an event to see its Error Response.

Fix: Match the error body to an entry in Customer data APIs and correct the source data or mapping. Sending the same event again fails the same way.

Hightouch retries the same rows on every run

Cause: Hightouch treats every 4xx and 5xx response as an error and retries it on every run until it succeeds. Common causes are a numeric or null user ID, a numeric event ID, a timestamp without a time zone, and the Identify 409 from a reused messageId.

Fix: Correct the model. Cast user IDs and event IDs to text, format times as ISO 8601 with Z, and exclude rows with no user ID, event name, or time. Use | json without quotes around it in the payload template. For a 409, add every trait column to message_key, or leave messageId out of the Identify template. See the Hightouch guide.

CSV upload says “That CSV is too large. Split it into smaller files and try again.”

Cause: The file is larger than 20 MB. A file with more than 50,000 rows shows a different message: “That file has N rows. Split it into files of 50,000 rows or fewer.”

Fix: Split the file into parts within both limits and import each part.

CSV upload says “That file is not a CSV. Choose a .csv file and try again.”

Cause: The file isn’t a .csv file. An empty file, a file whose first row is blank, or a file with an unclosed quote shows a different message: “That file could not be read as a CSV. It needs a header row and at least one column.”

Fix: Save the file as .csv with a header row and an email column, then upload it again.

CSV upload lists rows that weren’t imported

Cause: Those rows have a problem. The table gives the Row, Column, and Reason, such as “Duplicate of row N” for a repeated email.

Fix: Select Import valid rows only to import the rest, then fix the listed rows and import them separately. You can also correct the file and select Upload a different file.

The same person appears twice on Users after a CSV upload

Cause: CSV upload matches people by email. Without a user_id column, a later Identify call with a user ID creates a second person. A header of userId doesn’t count, because JustAI converts it to userid.

Fix: Include a column with the header user_id or User ID in every CSV upload. Contact your JustAI team to clean up existing duplicates. See CSV upload.

An S3 delivery landed, but profiles didn’t change

A successful upload confirms that the files reached S3, not that JustAI loaded them. Follow the acceptance checks your JustAI team confirmed for your import. Contact your JustAI team with the delivery location, time, expected row count, and synthetic test IDs. Do not replace files or retry a load until they confirm the correction procedure. See Plan an Amazon S3 file import.

Profile changes from a CSV upload don’t start a journey

Cause: Journeys that start when A profile attribute changes react to Identify calls. CSV uploads don’t start them. For a customer-specific file import, confirm its behavior with your JustAI team.

Fix: Send changes that must start journeys through the Identify API.

You need to load past events

Contact your JustAI team before planning an import. Confirm availability and acceptance checks before exporting or sending the history. Do not replay past events through Track: a matching event can start, advance, or end a published journey, regardless of its timestamp.

Iterable connection

“Verification failed: Iterable returned 401 : Unauthorized”

Cause: Iterable rejected the key. The key is wrong, it’s a client-side key for mobile or JavaScript, or the project is in Iterable’s EU data center. JustAI works only with projects in Iterable’s US data center.

Fix: In a US-hosted project, create a server-side key with full read and write access. Paste it, select Verify, then select Save API key. See Add your Iterable project.

Set header or Create profile fails after “Key verified”

Cause: Verify confirms only that the key can read from Iterable. A key without write access fails later, for example with “Unable to configure Iterable webhook: …”.

Fix: Replace the key with a server-side key that has full read and write access, then try again.

“This API key belongs to a different Iterable project than this connection’s sending profiles.”

Cause: The connection has sending profiles, and the new key comes from another Iterable project.

Fix: Create the new key in the same Iterable project. To use a different project, add a new connection.

“Iterable rejected this API key. Check the key and try again.”

Cause: The connection has sending profiles, and Iterable refused the new key.

Fix: Copy the key again from Iterable, or create a new server-side key, and save it.

“Iterable API key verification is temporarily unavailable. Try saving again.”

Cause: JustAI couldn’t check the key with Iterable at that moment.

Fix: Select Save API key again.

The Content data feed step reads “Generate a token and paste it into the data feed.”

Cause: The data feed ID is saved, but no feed token exists yet.

Fix: Select Generate token. Paste the token into the feed’s Authorization token field in Iterable and save the feed. If the step reads “Save changes to use this feed.”, select Save data feed.

You lost the feed token, or messages stop after a new token

Cause: JustAI shows a feed token only once. Generating a new token stops the old one at once. Until Iterable has the new token, Iterable can’t fetch the prepared content, and messages aren’t sent.

Fix: Select Generate a new token, then Generate new token. Paste the token into the feed in Iterable right away. See Set up the content data feed.

Caution

The current token stops working as soon as you generate a new one. Generate a new token only when you can update the feed in Iterable at the same time.

“…has sending profiles that read data feed <id>. Use a new connection to change its content feed.”

Cause: You can’t change the data feed ID after a connection has sending profiles.

Fix: Keep the current feed, or add a new connection with a new feed.

The System webhook step reads “Webhook not set up yet.” or Verify shows “No webhook found yet.”

Cause: JustAI can’t find its webhook in this Iterable project. The webhook is in another project, its endpoint differs from the one JustAI shows, or it isn’t saved.

Fix: In the project that your API key belongs to, create the system webhook with the endpoint copied from this connection. Select Save Webhook in Iterable, then Verify in JustAI. See Set up the system webhook.

“Webhook #<id> — needs the JustAI secret key”

Cause: JustAI found the webhook but hasn’t written its authentication header yet.

Fix: Select Set header.

“Webhook #<id> is disabled in Iterable — enable it to receive events”

Cause: The webhook’s status in Iterable isn’t Enabled.

Fix: Enable the webhook in Iterable, then select Verify in JustAI to refresh the step. You don’t need to set the header again.

“Webhooks haven’t loaded yet. Refresh to try again.”

Cause: JustAI couldn’t load the project’s webhooks from Iterable.

Fix: Refresh the page. If the message stays, check that the API key is saved and is a server-side key with full access.

Integrations shows Configured, but sends and opens don’t arrive

Cause: The Configured badge doesn’t check whether the webhook is enabled, and JustAI can’t see the webhook’s headers. Engagement stops when someone edits or removes the header JustAI added. It also stops when another JustAI connection, in any environment, takes over the webhook.

Fix: Open the connection and read the System webhook step. Select Verify, then Set header or Update header, whichever appears. Connect each Iterable project to one JustAI connection in one environment, and use a webhook only for JustAI.

Add profile is missing and the step reads “Complete the steps above to continue.”

Cause: The connection isn’t finished. Sending profiles need a saved API key, a saved data feed ID with a feed token, and a webhook that has the JustAI header and is enabled.

Fix: Complete each step until it shows its summary: “Key saved”, Data feed #<id>, and Webhook #<id>.

The profile form says “Register the content data feed on this connection first.” or “Save an API key on this connection first.”

Cause: The connection setup is incomplete.

Fix: Select Finish connection setup and complete the step named in the message.

From email shows “Senders unavailable” or doesn’t list your sender

Cause: “Senders unavailable” means JustAI couldn’t load senders from Iterable. The list shows only senders found on your project’s recent email campaign templates. When the list has any senders, you can’t type a new address.

Fix: For “Senders unavailable”, check the connection’s API key. To add a sender, use it on an email campaign template in Iterable first, wait a few minutes, and open the form again.

“No SMS message types in this project” or “No push message types in this project”

Cause: The Iterable project has no message type for that channel.

Fix: Create an SMS or push message type in Iterable, then open the form again.

“Iterable is still preparing this profile’s campaign. Save the profile again in a minute.”

Cause: Iterable created the campaign but hasn’t finished preparing it.

Fix: Wait a minute and select Create profile again.

“An Iterable sending profile with key “<key>” already exists on this connection.”

Cause: Another profile on this connection has the same name, or a name that differs only in case or punctuation.

Fix: Choose a different name.

“An Iterable connection can have at most 50 sending profiles.”

Cause: The connection has 50 sending profiles.

Fix: Remove profiles that no journey uses.

Sending profiles and test emails

“Turn on Ignore Frequency Cap on this profile’s campaign in Iterable and activate it before sending a test.”

Cause: The Ignore cap step isn’t done.

Fix: Open the campaign in Iterable. Under Delivery settings, turn on Ignore Frequency Cap, and save the campaign without activating it. In JustAI, select I’ve turned it on. If the campaign has no toggle, its message type isn’t capped, and you can select I’ve turned it on directly.

You selected I’ve turned it on before turning on the setting

Cause: JustAI doesn’t check the setting. It activates the campaign when you select I’ve turned it on, and Iterable locks the setting once the campaign is active.

Fix: Create a new sending profile and complete Ignore cap in order. Remove the old profile, then archive its campaign and template in Iterable.

“Add your company’s mailing address in Settings > Delivery before sending email. It appears in the footer of every email.”

Cause: Your organization has no mailing address. Test emails, proofs, and live Iterable email all need one.

Fix: An organization admin opens Settings > Delivery, enters the address on the Mailing address card, and selects Save. Other members see “Only admins can change this.”

“Finish the Iterable connection’s API key and content data feed before testing this profile.”

Cause: The connection’s API key or Content data feed step isn’t complete.

Fix: Complete both steps on the connection, then send the test again.

The test email doesn’t arrive

Cause: Iterable didn’t send it, or it went to spam. The Verify setup card shows the reason.

Fix: Check your spam folder, then match the message on the card:

Message	Fix
“Waiting for Iterable to accept the test.”	Wait a few minutes.
“This address is suppressed. Choose another test recipient.”	Send the test to another address.
“Iterable reported a bounce for this address.”	Send the test to an address that accepts mail.
“This workspace requires email consent, and the test address has none. …”	Ask your engineering team to send an Identify call that includes the test address in traits.email and a granted email consent decision. See Consent decisions in Identify. Then select Resend. To turn off the consent requirement while you test, talk to your JustAI team.
“The send failed. Check the profile’s campaign in Iterable and the connection’s API key.”	Check that the campaign exists and is active in Iterable, and that the API key has full access.
“This test never reached Iterable. Send a new one.”	Send a new test.
“We couldn’t confirm whether Iterable accepted the test. …”	Check your inbox and Iterable’s activity. If the email arrived, select Click here to confirm in it.

If no message appears, select Resend next to “Nothing yet?”.

“This link isn’t valid. Send a new test email from this profile.”

Cause: The confirmation link is damaged or incomplete.

Fix: Send a new test email and open the link in the newest email.

The confirmation link doesn’t confirm the profile

Cause: You opened the link in a browser where you aren’t signed in to JustAI.

Fix: Sign in to JustAI, then open the link again in the same browser. JustAI shows “Profile confirmed!”. If you see “This profile could not be confirmed. Open the link again.”, open the link again.

The profile stays Setup needed after Iterable accepted the test

Cause: Iterable’s acceptance doesn’t verify the profile. Only the confirmation click does.

Fix: Open the email “Confirm your JustAI sending profile” and select Click here to confirm. The card then reads “Verified · test email confirmed”.

An SMS or push test code doesn’t work

Cause: A code works for one hour, and only the newest test’s code counts. You get five attempts, and you must wait a minute between tests.

Fix: Match the message:

Message	Fix
“That code doesn’t match. N tries left.”	Enter the code from the newest message.
“That code doesn’t match. Send a new test text.”	Send a new test, then enter its code.
“This test text has expired. Send a new one.”	Send a new test. Push shows “This test push has expired. Send a new one.”
“A test text was just sent. Wait a minute before sending another.”	Wait a minute, then send the test.

For SMS and push tests, enter the email of an Iterable user who has a registered phone number or device.

The journey shows Needs setup ↗ for the profile

Cause: The sending profile isn’t Verified. A send or proof through it fails with “Verify this Iterable sending profile before sending. Send a test from the profile and confirm it from the email.”

Fix: Complete Verify setup on the profile. See Create a sending profile.

Your Iterable connection isn’t in the journey’s integration list

Cause: A connection appears in Journey settings > Delivery only after it has at least one sending profile.

Fix: Create and verify a sending profile on the connection.

“Text proofs don’t send through Iterable. Send a test text from the journey’s Iterable SMS profile in Settings instead.”

Cause: Journey proofs for SMS and push don’t go through Iterable. A push proof shows a matching message.

Fix: Send a test text or test push from the sending profile in Settings > Integrations.

A run shows Not sent with “Sending is blocked for this recipient.” or “Marketing consent is missing.”

Cause: The person is suppressed in JustAI, or your organization requires email consent and the person has none. JustAI applies these checks before it hands email to Iterable. To see a person’s run, open the published journey from Journeys, search for them in Recent runs, and select the run.

Fix: Check the person’s Subscription on Users. Send consent decisions through the Identify API. See Identity and consent.

Messages arrive blank, with the wrong subject, or in the wrong subscription category

Cause: Someone edited a JustAI · <profile name> template or campaign in Iterable. JustAI doesn’t check these templates or warn when they change.

Fix: Undo the edit in Iterable. You can also create a new sending profile and switch your journeys to it.

A sending profile can’t be removed

Cause: A journey draft, published version, or unfinished run uses the profile. JustAI lists those journeys.

Fix: Choose another profile in those journeys, update their published versions, and finish or stop any remaining runs. Then remove the profile.

A test email doesn’t appear in journey analytics

Cause: Journey analytics count live journey sends. A sending-profile test email belongs to no journey.

Fix: Check the journey’s email step after its first live sends. It shows Sent, Delivered, Opened, and Clicked.

Contact your JustAI team

If a fix doesn’t work, recheck the setup with the Launch checklist and look for a quick answer in the FAQ. Then contact your JustAI team.

To reach your JustAI team, select Support Portal at the bottom of the left sidebar, then select New request. Enter a Title and a Description, and select Submit request. Support Portal lists each request and your JustAI team’s reply.

Include these details:

• your organization name and the environment, as shown in the account menu
• what you did, what you expected, and what happened, with the time and time zone
• for an API request: the endpoint path, the HTTP status, the full response body, the messageId, and the user ID of a test person
• the API key’s suffix from Settings > API keys, such as xxxxx1a2b3
• for a data source: the tool, and the name of the destination, mapping, or sync
• for Iterable: the connection’s Account name, the sending profile’s name, and the webhook and data feed numbers that JustAI shows
• screenshots of the JustAI screen

Never share secrets

Don’t send JustAI API keys, Iterable API keys, feed tokens, passwords, or AWS access keys in a ticket, email, or screenshot. Use test user IDs and synthetic data in examples. For an S3 file import, grant access with an IAM policy for the role your JustAI team gives you.