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.
Client Abort
We detected the premature request’s termination on the client side. This resulted in request ending as failed.