Articles in this section

API Response Codes

When you use Iterable's REST API to interact with a project, Iterable responds with standard HTTP status codes to indicate the success or failure of a request, with some responses having additional context.

This article describes Iterable's HTTP response codes, their corresponding HTTP status, and what they mean.

Response codes, response bodies and their schemas vary based on the endpoint, and are subject to change without prior notice.

# In this article

# 200

# OK

This is the standard generic response for successful HTTP requests. The response payload varies depending on the endpoint.

# GET requests

For a successful GET request, the response usually contains the requested or updated resource as a JSON body of the content type application/json. However, some endpoints may return a different content type, such as text/csv.

Example response from GET /api/export/userEvents:

{
    "email": "user@example.com",
    "messageTypeId": 0,
    "reason": "MessageServiceError",
    "templateId": 0,
    "messageId": "9c438a20d26e4e9f8ad4edea23f811cd",
    "createdAt": "2023-10-26 23:43:55 +00:00",
    "contentId": 0,
    "campaignId": 0,
    "channelId": 0,
    "itblInternal": {
        "documentCreatedAt": "2023-10-26 23:43:55 +00:00",
        "documentUpdatedAt": "2023-10-26 23:43:55 +00:00"
    },
    "_type": "smsSendSkip"
}

# POST and PUT requests

For a successful POST or PUT request that creates or updates data, the response typically contains a JSON body describing the result of the action.

Example response from POST /api/users/update:

{
    "msg": "User successfully created/updated.",
    "code": "Success",
    "params": null
}

# 201

# Created

This status code indicates that a resource has been successfully created.

Example response from POST /api/snippets:

{
    "snippetId": 12346
}

# 202

# Accepted

This status code indicates that a request has been accepted for processing, but the processing has not been completed. This is common for asynchronous operations.

# 400

# BadJsonBody

The JSON request body is invalid. Make sure your request body is properly formatted JSON—check for missing or extra commas, or unclosed brackets.

TIP

You can use a JSON validator tool to help identify and fix formatting issues before sending your request.

# BadParams

The request is missing required parameters, or the provided parameters are invalid. Check the API documentation for the specific endpoint you are using to ensure all required fields are included and correctly formatted.

Example response:

{
    "msg": "Update user failed invalid userId (invalid character (non-ascii or non-printable)): ­.",
    "code": "BadParams",
    "params": null
}

# BatchTooLarge

The batch of items in the request exceeds the allowed limit. Reduce the number of items in the batch and try again.

# EmailAlreadyExists

The email provided for user creation or migration already exists.

# ForgottenUserError

The operation cannot be performed because the user has been forgotten (anonymized or deleted). Once a user has been forgotten, they must be recovered. To learn more, read Responding to GDPR Requests.

# InvalidEmailAddressError

The email provided in the request is invalid. To learn more, read Email Validation in Iterable.

# InvalidJwtPayload

The JWT (JSON Web Token) payload is invalid or malformed.

# InvalidUserIdError

The userId provided in the request is invalid. This can happen when the userId is not an accepted value. To learn more, read about UserID Validation in Iterable.

# JwtUserIdentifiersMismatched

The user identifiers in the JWT don't match the user identifiers in the request. To learn more, read JWT-Enabled API Keys.

# QueueEmailError

The message could not be queued due to a client-side issue.

# RequestFieldsTypesMismatched

The data types of one or more fields in the request don't match the expected types and the request couldn't be processed. To learn more, read Field Data Types.

# UniqueFieldsLimitExceeded

The request would exceed the limit for unique fields.

# UnknownEmailError

The email provided does not correspond to an existing user.

# UnknownUserIdError

The userId provided does not correspond to an existing user.

# UserIdAlreadyExists

The userId provided for user creation already exists.

# 401

# BadApiKey

The API key is either missing or invalid. Check your API key and permissions. For more information, read API Keys.

Example response:

{
    "msg": "Disabled API key or insufficient privileges",
    "code": "BadApiKey",
    "params": {
        "ip": "198.51.100.11",
        "endpoint": "/api/export/data.csv",
        "apiKeyIdentifier": "00000000",
        "apiKeyType": "JavaScriptSDK"
    }
}

# BadAuthorizationHeader

The authorization header is missing or improperly formatted.

# Unauthorized

The request lacks valid authentication credentials. This is a general code; more specific codes like BadApiKey or BadAuthorizationHeader may also apply.

# 403

# Forbidden

The requested action is not allowed for the user or API key type.

# ForbiddenParamsError

The request contains parameters that are not allowed for the authenticated user or API key.

# 404

# NotFound

The requested resource could not be found.

# 409

# ExternalKeyConflict

A conflict occurred with an external key, such as attempting to create a user with an external ID that's already in use.

# ForgottenUserError

The operation cannot be performed because the user has been forgotten (anonymized or deleted).

# Conflict

This happens when a conflict occurs, such as attempting to delete a list that is still in use (by a journey for example).

# 429

# RateLimitExceeded

The number of requests has exceeded the allowed rate limit.

# 500

# DatabaseError

A database operation was unsuccessful.

# GenericError

A general server error has occurred. This can have multiple causes, such as a failure to create a new user or trigger a workflow with an invalid list.

# QueueEmailError

The message could not be queued due to a server-side problem.

# Further reading

Related articles