Errors

Error messages

Error messages are unified and typically contain a logRef field, which is a unique identifier that can be used when talking to our customer support team.

Individual errors have an about section that links back to this documentation.

{
    "logRef": "64bb72b4-0a92-11e8-ba89-0ed5f89f718b",
    "message": "Bad request",
    "_embedded": {
        "errors": [
            {
                "path": "subject",
                "message": "may not be empty",
                "source": "JSON",
                "_links": {
                    "about": {
                        "href": "http://developer.helpscout.net/mailbox-api/overview/errors#NotEmpty"
                    }
                }
            },
            {
                "path": "status",
                "message": "Expected one of these: 'active', 'spam', 'open', 'closed', 'pending'",
                "rejectedValue": "Wrong",
                "source": "JSON",
                "_links": {
                    "about": {
                        "href": "http://developer.helpscout.net/mailbox-api/overview/errors#EnumValue"
                    }
                }
            }
        ]
    },
    "_links": {
        "about": {
            "href": "http://developer.helpscout.net/mailbox-api/overview/errors"
        }
    }
}

Errors that you might encounter when working with the API.

Error codes

Empty value

Field cannot be empty.

Value not supported

Provided value was not among predefined set of values.

Size

Value length must be in a predefined range. Please check documentation for the endpoint you were calling.

Not well-formed email address

Value is not a well formed email address.

Null value

Field cannot be null.

Malformed date

The value must be a valid ISO 8601 date with the format yyyy-MM-dd'T'HH:mm:ss'Z', for example 2017-03-31T23:30:01Z.

Invalid number

Value must be a number of predefined quality, for example must be greater than or equal to 5.

Invalid identifier

Value is not a valid entity identifier. For example you may encounter this error if a negative number is used.

Access denied

You are not allowed to access the requested resource. There can be multiple reasons for this error - for example, the API is disabled for your company, payment information is missing or you don’t have access to features like Reports.

API not enabled

While your access token is valid, you are not allowed to use the API.

Payment missing

While your access token is valid, your payment information is either missing or it expired. Please see our documentation for more information on resolving billing issues.

Cannot delete attachment from published conversation

Attachments can only be deleted from drafts, not published conversations.

Invalid URI

The endpoint URI is not well formed. While the API always tries to explain the specific error and pinpoint wrong query parameters it is not always possible. Please check documentation for the endpoint you were calling.

Invalid JSON

The request body either isn’t well formed JSON or JSON structure doesn’t conform to the endpoint’s specification - number is used instead of object or the other way around. Please check documentation for the endpoint you were calling.

Conflict

Entity cannot be created because conflicting entity already exists. Typical example is when you try to add a customer email that is already being used by another customer.

Invalid number

The provided value is not a non-negative integer (i.e. five instead of 5321).

Invalid media type

API expected JSON Content-Type header but received something else. See documentation for details.

Invalid HTTP method

The given endpoint does not support the HTTP method used, see the error message for list of supported HTTP methods and/or consult the documentation for the particular endpoint.

Conversation Locked - Too many threads

The maximum number of threads in a single conversation was reached. If you want to add a new thread, create a new conversation. If you wanted to create a conversation, please ensure the number of threads is below 100.

Conversation Locked - Conversation is too old

Company policy prevents updating old conversations. If you want to add a new thread, create a new conversation.

Allowed Patch Operations

You either used invalid JSONPatch operation or the operation you used is not permitted for the update path. For example you can only remove field that is nullable. Please consult the documentation for the particular endpoint.

Missing header

The request is missing a specified header.

Valid Conversation Owner

The user ID is not a valid conversation owner - it has to be ID of a user from your account.

Valid Imported Thread

When creating imported threads it is possible to set a createdAt value, but only if imported field is set to true.

Enum Value

The provided value has to be from a predefined list of values, the error message provides list of the allowed values.

List Of Enum Values

The provided list of values has to be from a predefined list of values, separated by comma. The error message provides a list of the allowed values.

Rejected request

The request was rejected because the URI did not conform to the rules. Please consult the documentation for the particular endpoint.

Cannot Run Workflow

Only manual workflows can be executed via the API and all conversation IDs must belong to existing conversations from the workflow’s mailbox

Internal Timeout

An internal call timed out and the API was not able to complete your request. It is safe to retry the request after a short delay. This is a server error but the HTTP status 504 indicates that a retried call should finish as expected.

Invalid Attachment

Attachment data must be valid Base64 formatted string and the original file size must be less than 10MB

Invalid Thread Author

Certain thread types support optional user field that overrides the thread creator (author). This user must have the correct rights for the mailbox. If you received this error, the user field was wrong - either the user is invalid or doesn’t have the correct access rights.

Invalid Mime-Type

Attachment Mime-Types should consist of full and valid Mime-Type names.