HTTP status codes tell you whether a request to Insider One's APIs completed and, if not, why. The first digit of the code tells you the type of response:
2xx means the request is completed.
4xx means a client error occurred, usually a validation issue with your credentials, payload, or parameters.
5xx means a server error occurred on Insider One's side, not yours.
The exact message varies by API, and different endpoints can return the same code with different text. Before you send a request, format your payload as valid JSON: use double quotes for both keys and values, not single quotes.
This article groups the errors you'll run into by cause for troubleshooting purposes:
Success responses (2xx)
200 OK: The request is completed. On bulk endpoints, check the response body for a fail object; see Partial success responses below. Example response: { "data": { "successful": { "count": 1 }, "fail": {} } }
200 Campaign Created: Your campaign was created successfully. Example response: { "response": "Campaign Created." }
201 Created: Your campaign was created, and the response includes its IDs. Example response: { "status_code": 201, "content": { "message": "Campaign created successfully.", "builder_id": "1000", "campaign_id": "1230" } }
201 Created (builder): A resource was created and assigned an ID. Example response: { "message": "created", "id": "builderID" }
202 Accepted: Insider One accepted the request for processing. Example response: { "message": "Accepted", "status": 202 }
Partial success responses (200 OK with failures)
Bulk and batch endpoints can return 200 OK even when part of the request failed. Insider One calls this a partial success response. The request itself was received and processed, but individual records inside it can fail independently of one another.
{
"data": {
"successful": { "count": 1 },
"fail": {}
}
}successful.count: The number of records the endpoint processed without an error.
fail: An object listing the records that failed, along with the reason for each failure. An empty fail object means every record succeeded.
The HTTP status alone doesn't tell you whether a bulk request fully succeeded, so always check the response body for a populated fail object before treating it as complete. Correct and resend any record listed there on its own. This is different from a full success, where fail is empty, and from the request-level errors covered in the sections below, where Insider One rejects the entire request instead of processing part of it.
Example: Upsert User Data API
The Upsert User Data API is a common source of partial success responses because it validates the payload's structure separately from validating each user record. Insider One returns a 200 status as long as the request itself is well-formed, even if every record inside it fails:
{
"data": {
"successful": {},
"fail": {
"count": 1,
"errors": {
"users.0.events.0.event_params.*.required": [
"event_group_id parameter is required on purchase event",
"unit_sale_price parameter is required on purchase event"
]
}
}
}
}Here, fail.count gives the number of user records Insider One couldn't process, and fail.errors is an object keyed by the specific field path that failed, each listing the validation messages for that field. Other common causes on this endpoint, identified the same way through fail.errors, include:
Missing identifier or insider_id: "either insider_id or identifiers must be specified"
Invalid email format: "invalid email address: sample"
UUID sent as the wrong data type: "value must be string: uuid"
Unsupported identifier key: "key must be one of phone_number(pn), email(em) or uuid"
Invalid phone number format: "invalid phone number: 12345"
Check fail.errors for the exact field and message, correct that record, and resend it on its own.
Accepted doesn't always mean delivered
For messaging endpoints (web push, app push, SMS, email, and WhatsApp), a 200 or 202 response means Insider One accepted and queued the message, not that every recipient received it. Delivery still depends on factors outside the request itself, such as a device being offline, a push token being rejected by Apple or Google, or a provider-side bounce. Check your campaign or channel analytics for actual delivery outcomes; a successful API response only confirms the request was valid and queued.
Authentication and authorization errors
These errors mean Insider One couldn't verify who's making the request, or that the request lacks permission to do what it's asking. See API Authentication Tokens for details on generating and managing keys.
Missing or unrecognized API key (400, 401, 403)
Insider One returns different codes for this depending on the endpoint, but the fix is the same: confirm you're sending the X-Api-Key header with a valid, active key tied to your account.
No X-Api-Key header sent:
{"error": "No api key provided"}Header sent, but the key is invalid:
{"error": "Invalid api key"}No customer account matches the key:
{ "response": "No Partner Found With Api Key." }Key is empty or malformed:
{ "error": "bad_api_key", "message": "'api_key' is either empty or wrong. You can get your API key from Insider Dashboard" }Key doesn't match any record on file:
{ "error": "Bad Api Key." }Generic unauthorized response:
{ "errors": [ { "message": "unauthorized" } ] } { "error": "unauthorized" }Invalid, expired, or revoked API key (401)
{ "message": "The provided API key is invalid, expired or revoked", "status": 401 }{ "status": false, "message": "Partner token authentication failed." }First, check the request headers, since another user on the account may have deleted the key. Confirm in the InOne panel that the key is still active, including any IP whitelist checks that apply to your account. If the key no longer exists, generate a new one. If a newly generated key still fails, contact the Insider team.
API token and account don't match (401)
{ "status_code": 401 }{ "success": false }Your API token and customer account name must match for the request to be authorized. Double-check that you're using the token issued for this specific account.
Verification code invalid or expired (401)
{ "errors": [ { "message": "invalid code" } ] }The code sent with the request either doesn't match what Insider One expects for this action or has expired. Request a new code and retry.
Resource not found for this key (404)
{ "errors": [ { "message": "code not found", "field": "code" } ] }The value doesn't correspond to an existing resource on your account. Confirm that the ID or code you're referencing exists and belongs to the account associated with your API key.
Sending domain not authenticated (401)
{ "message": "The domain you are trying to use is not authenticated. Please create a support ticket for the Insider Support Team to authenticate it.", "status": 401 }If Transactional Email Domain Authentication is enabled on your account, you can send only from domains registered through Add More Domains during onboarding. Verify that your sending domain is authenticated and verified in SendGrid before opening a support ticket; an unverified domain risks spam or blocking.
Insufficient access to this endpoint (403)
{ "success": false, "message": "Access Denied. You do not have sufficient access to perform this action." }{ "success": false }Confirm you're using an API key that has permission for this specific endpoint. This response also occurs when the account can't be validated.
Identity and payload validation errors
These errors mean Insider One received the request but rejected it: a required field is missing, a value conflicts with an existing record, or the payload isn't formatted correctly.
Payload isn't valid JSON (400)
{ "success": false, "message": "Request data is not in valid JSON format." }{ "error": "invalid request payload" }Before you retry, check the following:
Validate the payload with a JSON linter to catch syntax errors like trailing commas or mismatched brackets.
Confirm you're using double quotes for keys and values, not single quotes.
Set the Content-Type: application/json header, and confirm your HTTP client is JSON-encoding the object rather than sending a concatenated string.
Required parameter missing (400, 422)
Insider One returns this pattern whenever a required field is omitted from the payload. The field name is dynamically inserted into the message:
{"error": "<Field> is required."}E.g., "error": "parameter 'subject' is required". Other endpoints return the same idea in a structured format:
{ "status_code": 422, "errors": { "field": ["The <field> is required."] } }Check the response for the specific field name, add it to your payload, and retry.
Missing content, subject, or content type (400)
Missing message content: { "errors": ["Missing 'content' parameter"], "message": "bad-request", "status": 400 }
Missing subject line: { "errors": ["Missing 'subject' parameter"], "message": "bad-request", "status": 400 }
Missing content type header: { "message": "content type must be application/json", "status": 400 }
Add the missing field or header and set Content-Type: application/json in the request.
Missing 'to' or 'from' parameter (400)
{ "errors": ["Missing 'to' parameter"], "message": "bad-request", "status": 400 }{ "errors": ["Missing 'from' parameter"], "message": "bad-request", "status": 400 }{ "errors": ["Missing 'email' on 'tos' parameter"], "status_message": "failed to validate request" }Add the missing recipient or sender field to your payload.
Missing or malformed user/identifier data (400)
No user included in the request: {"error": "users must be defined: bad request"}
No identifier included at all: { "error": "empty_insider_identifiers", "message": "'insider_identifiers' object need to have at least one identifier" }
The identifier key isn't enabled in your account's Identity Resolution Management (IRM) settings: { "error": "no valid identifier: bad request" }. Check your IRM settings; you can only send identifiers configured there. For example, if phone number isn't set up as an identifier for your account, you can't send a payload using it as one.
Identifier update conflicts (400)
Old and new identifier values are the same: { "error": "identifier values are the same: bad request" }
Old or new identifier value is missing (both are required): { "error": "there must be exactly 1 entry for both new and old identifiers: bad request" }
New identifier value is already assigned to a different user: { "error": "new identifier already has a user assigned to it: bad request" }. Identifiers are unique per user. To reassign the value, first remove it from the other user with the Identity API, then send it for the new user.
Attempting to delete a user's only identifier: { "error": "you cannot delete the sole identifier specified for a user: bad request" }. A user profile must always keep at least one identifier.
No user matches the identifiers sent: {"error": "no such user for these identifiers: no data"}
Payload exceeds a size or count limit (400, 422)
Request body larger than 5 MB: {"error": "request body is bigger than maximum allowed size 5,000,000 bytes"}
Product list exceeds 100 items: { "success": false, "message": "Maximum allowed size is 100." }
Overall request size exceeds the allowed maximum: { "success": false, "message": "Maximum allowed request size is exceeded." }
Record count exceeds the allowed maximum: { "success": false, "message": "Maximum allowed record count is exceeded." }
Split the payload into smaller batches and resend.
Config, partner, or unifier value is invalid (400)
Config object is malformed: { "success": false, "message": "Config is invalid." }
The partner value doesn't match your account's panel name (for example, sending "my panel" when the panel name is "mypanel"): { "success": false, "message": "Partner is invalid." }
Check that the value you're sending exactly matches what's configured for your account.
Invalid callback URL (400)
{ "errors": ["Invalid callback URL in 'url' on 'callback'"], "status_message": "failed to validate request" }This triggers for malformed URLs, such as a missing scheme ("htp:/domain"), a missing domain ("domain path"), a stray space ("example .com"), or an empty string. Send exactly one valid, properly formatted URL:
"callback": { "url": "https://insiderone.com" }Duplicate segment name (400)
{ "statusMessage": "segment name already in use" }Choose a segment name that isn't already in use on your account.
Field-level validation errors (400)
Some endpoints return validation failures as a list, naming the field and the rule it broke:
{ "errors": [ { "message": "this field is required", "field": "text" } ] }{ "error": "$message" }For a structured version with more detail, some endpoints return:
{
"status": "Invalid",
"data": null,
"error": null,
"validations": [ { "type": "...", "message": "..." } ]
}Business rule violation (400)
{
"status": "BusinessException",
"data": null,
"error": { "code": "...", "message": "..." },
"validations": null
}This means the payload is well-formed but violates a business rule specific to the endpoint (for example, a state transition that isn't allowed). Check the error.message field for the specific rule.
Payload format is invalid (405)
{ "error": "Invalid Payload." }Review your payload structure against the endpoint's documentation.
No changes to apply (409)
{ "errors": [ { "message": "no changes detected" } ] }This means the values in your update, patch, or modify request are identical to the existing record, so there's nothing to change. Some endpoints instead return 200 OK and treat the request as idempotent; others return 409 Conflict because, technically, an update was requested, but nothing differed. Check which behavior the specific endpoint documents.
Dependency failed (424)
{ "message": "SERVICE:-" }An upstream service the request depends on didn't respond as expected. Retry the request; if it keeps failing, contact the Insider team with the request details.
Channel-specific errors
These errors are specific to a particular messaging channel, integration, or analytics endpoint, not authentication or general payload validation.
Push: invalid certificate (400, 422)
Certificate isn't validated: { "success": false, "message": "You do not have a validated certificate. Please check Certificate section under Insider's Settings." }
No certificate provided at all: { "response": "No Push Message Certificate is Provided." }
See Push Certificates for instructions on adding push certificates for iOS, Android, and Huawei.
Push: invalid notification payload (400)
Notifications array is empty: { "error": "invalid_notifications", "message": "'notifications' is empty, add some notification objects" }
Notifications array has more than 20 objects: { "error": "invalid_notifications", "message": "'notifications' can't have more than 20 objects" }
Deep link contains the blacklisted aps key: { "error": "blacklisted_deeplink", "message": "deepLink can't contain 'aps' key" }. Remove aps from the deep link value.
camp_id or channel_id is zero or negative: { "error": "negative_integer", "message": "'camp_id' and/or 'channel_id' must be greater than zero" }
advanced_push_type isn't one of the supported values: { "error": "invalid_advanced_push_type", "message": "'advanced_push_type' must be either Carousel or Slider" }
SMS and WhatsApp: invalid channel or recipient (400)
channel isn't set to a value the endpoint supports: { "errors": [ { "message": "this field must be one of these:sms", "field": "channel" } ] } (or whatsapp, depending on the endpoint)
to isn't a valid phone number for SMS: { "errors": [ { "message": "channel information must be a valid phone number for sms", "field": "to" } ] }
Confirm the channel value matches the endpoint you're calling, and that phone numbers are in a valid format.
In-app messages: not found or invalid parameters (404, 400, 406)
Requested in-app message doesn't exist: { "error": "inapp not found" }
Analytics request missing both required parameters: { "error": "either 'inapp_id' or 'created_between' must be provided" }
Analytics request includes both when only one is allowed: { "error": "provide either 'inapp_id' or 'created_between', not both" }
from or to date isn't in YYYY-MM-DD format: { "error": "invalid date format for 'from'; expected format is YYYY-MM-DD" }
to date is earlier than from date: { "error": "'to' date must be after or equal to 'from' date" }
Date range exceeds 90 days: { "error": "date range must not exceed 90 days" }
Analytics history is limited to the past year; the endpoint returns a 406 Not Acceptable response because Insider One can provide analytics data only for the last year.
CRM integration: unifier or connection errors (400)
CRM unifier referenced in the request doesn't exist on InOne: { "success": false, "message": "No CRM Unifier found in InOne." }
Insider One couldn't reach the CRM to retrieve attributes: { "success": false, "message": "Could not get CRM Attributes List." }
Confirm the unifier is configured in InOne, and that the CRM connection is active.
Campaign or channel resource conflicts (500)
A channel with this identifier already exists: { "errors": [ { "message": "channel already exists" } ] }
Referenced campaign doesn't exist: { "message": "SERVICE:-Campaign not found" }
These return a 500 status even though they reflect a conflict with existing data rather than a server fault. Check the channel or campaign identifier you're sending against what already exists on your account.
Rate limiting and availability errors
These errors mean you've sent more requests, records, or attempts than Insider One allows in a given window, or that Insider One's infrastructure is temporarily unable to process the request.
Too many requests (429, 403)
Shared limit with the User Upsert API, 25,000 requests per minute total: { "error": "rejected: too many requests" }. Wait before sending new requests, and check whether other integrations on your account share this limit.
General rate limit exceeded, 30 requests per minute: { "error": { "message": "Too many attempts, please slow down the request. 30 Requests/minute is allowed." }, "status": 403 }
Generic rate limit response: { "message": "rate limited" }
Too many attempts (429)
{ "errors": [ { "message": "maximum attempts exceeded", "field": "code" } ] }You've retried a code-based action (such as a verification code) more times than allowed. Wait for the limit to reset before trying again.
Request volume exceeds the allowed limit (400)
{ "success": false, "message": "The request is denied. More than 10000 records were sent." }This is a per-request volume limit rather than a requests-per-minute limit: split the batch into smaller requests, each under 10,000 records.
Server error (500)
{ "success": false, "message": "The request processing has failed because of an unknown error." }{ "errors": [ { "message": "server error" } ] }{
"status": "Error",
"data": null,
"error": { "code": "500 INTERNAL_SERVER_ERROR", "message": "..." },
"validations": null
}Insider One receives an alert whenever this response is returned. If it persists across retries, contact the Insider team with sample requests.
Service temporarily unavailable (503)
The service is temporarily unavailable due to server overload or maintenance. Check whether other recent requests show the same pattern, since the system may need to scale temporarily. Retry within a 15-minute window, since a 503 can occur at any moment. If 503 responses continue past 15 minutes, contact the Insider team with sample requests.
Server timeout (504)
The server didn't receive a timely response from an upstream service. If you resend a request with the same content for the same user within 15 minutes, Insider One returns:
{ "status_message": "This request has already been received and is being processed. Any duplicate content from the user will be ignored for the next 15 minutes." }This duplicate-prevention mechanism means users won't receive the same message twice, even if you retry. Check the overall 504 ratio across your other requests, since system load or upstream latency can both trigger this. Retry within 15 minutes to avoid message loss. If 504 responses continue past 15 minutes, contact the Insider team with sample request details.
Cloudflare network error (520)
An unexpected error occurred on the Cloudflare network, and the request wasn't processed. Retry with random delays spread across a 5-minute window rather than retrying immediately, so server resources can recover, and traffic can stabilize. This same retry approach applies to all availability errors in this section.
Summary
Insider One's API errors break down into four causes: who's making the request (authentication), what's in the payload (identity and validation), which channel or feature the request touches, and how often or how much you're sending (rate limiting). When you hit an error, start by identifying which of these four groups it falls into, then check the specific cause against the entries above.