Errors

A failed call answers with an HTTP status from the 4xx or 5xx range. The status is what your code should act on. The body, when there is one, explains the failure to a person.

How it works

Most errors carry a JSON body. Its error field holds a message in English. A failure raised while the call was being handled gives the full form:

{
  "type": "https://httpstatuses.io/404",
  "title": "Not Found",
  "status": 404,
  "error": "Thread not found",
  "message": "Thread not found",
  "correlationId": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}

Field	Meaning
status, title	The HTTP status and its name.
error, message	The same text, saying what went wrong.
correlationId	Identifies this call. Give it to Replyco support when you report a problem.

A check on the request itself, such as an id that is not a UUID, answers with error alone. Every response also carries the identifier in the X-Correlation-Id header, so you can log it for calls that succeed too.

Status	When you get it
400	The request is not valid: a required field is missing, the JSON is malformed, an id is not a UUID, a sort field is not allowed, a page holds more than 100 items, or the operation’s own rules refuse it.
401	The access token is missing, has expired or is not valid. Usually there is no body.
403	The user the token stands for may not do this. There is no body.
404	There is no record with this id for your company.
429	You exceeded a rate limit.
500	The call failed on Replyco’s side. The body gives a general message and the correlationId, never the cause.
502	A service the operation relies on did not answer; nothing was created. The body gives a general message and the correlationId.

Handle errors by status:

• Read the status first. Treat the body as text to log or show. Don’t branch on the wording of a message.
• Not every error has a body, and a body may be a plain message rather than an object, so parse it defensively.
• On several operations, a read of one record by id that finds nothing answers 204 No Content with an empty body. Treat 204 as “no such record”.

Retrying

Status	Retry?
400, 403, 404	No. The same request fails the same way; fix the request first.
401	Once, after you refresh the token or sign in again.
429	Yes, after the rate-limit window has passed. See Rate limits.
500, 502	Yes, a few times, with a growing pause between attempts.

No operation takes an idempotency key, so the API does not recognise a repeated create as the same request. When a create such as POST /openapi/customer or POST /openapi/thread/create times out without an answer, look the record up before you send it again.

Every documented error

Status	Meaning	Returned by
400	Invalid request data (e.g., missing required fields, invalid marketplace type); Invalid request data or attempting to update non-custom integration; Cannot delete - account is not a custom integration; Invalid credentials, missing fields, or unsupported grant type; The request is invalid (missing fields, no condition, no accounts, or startDate after endDate).; The request is invalid.; An attachment of the message is stored in an unsupported location; Invalid request body; Invalid filter parameters; Invalid pagination parameters; Invalid request (e.g., missing required fields, chat is closed); Invalid status value; Request validation failed (missing required fields or malformed body).; Invalid pagination parameters (e.g., page size exceeds 100); Invalid paging or date range. The response body carries the reason in its ‘error’ field; Invalid request data; Invalid folder or thread ID; Invalid thread IDs; Invalid request - missing required fields, invalid thread, or an attachment that is too large, of a file type the integration does not accept, or missing its file name. The response body carries the reason in its ‘error’ field; The request is invalid; the body’s error says why.; Invalid date parameters; Invalid year parameter; The request is invalid (e.g. text is missing).; The request is invalid (e.g. subject is missing or too long).; The request is invalid (e.g. title is missing or too long).; The request is invalid (e.g. name is missing).; Invalid request (e.g., empty thread list, too many IDs); Invalid request (e.g., empty list, too many IDs); Invalid request - missing required fields, an account that is not a Custom Integration, or an attachment that is too large, of a blocked file type, or missing its file name. The response body carries the reason in its ‘error’ field; Invalid request (e.g., less than 2 IDs, more than 10 IDs); The note is missing or empty. The response body carries the reason in its ‘error’ field; Invalid request (e.g., past date, too many IDs, invalid date range); Invalid request (e.g., past date, invalid date range); Invalid filter parameters (e.g., page size exceeds 100)	POST /openapi/account/addcustomintegration, PUT /openapi/account/updatecustomintegration, DELETE /openapi/account/{id}, POST /openapi/auth/token, POST /openapi/autoresponder, PUT /openapi/autoresponder/{id}, GET /openapi/bytefiles/messageattachments/{messageId}, PUT /openapi/chat/draft/{chatId}, POST /openapi/chat/paged, GET /openapi/chat/pagedchatmessages/{chatId}, POST /openapi/chat/sendmessage, POST /openapi/chat/status/{chatId}/{status}, POST /openapi/customer, GET /openapi/customer/paged, POST /openapi/feedback/paged, POST /openapi/folderthreads/assignfolderstothreads, DELETE /openapi/folderthreads/deletefolderfromthread, POST /openapi/folderthreads/removefoldersfromthreads, GET /openapi/message/pagedthreadmessages/{threadId}, POST /openapi/message/send, POST /openapi/messagerule, PUT /openapi/messagerule/{id}, POST /openapi/order, POST /openapi/reporting/ai/csvreport, POST /openapi/reporting/aiusagebyactiontypes, POST /openapi/reporting/aiusagebyuser, POST /openapi/reporting/autoresponsesusage, POST /openapi/reporting/avaragetimeinfo, GET /openapi/reporting/billingchatsperchannel, GET /openapi/reporting/billinggeneral, GET /openapi/reporting/billingticketperchannel, POST /openapi/reporting/casescalculation, POST /openapi/reporting/casesstatusesinfo, POST /openapi/reporting/comparecreatedansweredresolved, POST /openapi/reporting/countrieslist, POST /openapi/reporting/dueoverduecountinfo, POST /openapi/reporting/dueoverduepercentageinfo, POST /openapi/reporting/instantmessageschatscount, POST /openapi/reporting/instantmessageschatsperaccount, POST /openapi/reporting/instantmessageschatspermarketplace, POST /openapi/reporting/instantmessagesoverview, POST /openapi/reporting/instantmessagesuserperformance, POST /openapi/reporting/itemssoldineachchannel, POST /openapi/reporting/messagescountinfo, POST /openapi/reporting/moneyfromeachchannel, POST /openapi/reporting/notsentmessagescount, POST /openapi/reporting/productsearnedmoney, POST /openapi/reporting/templatesusage, POST /openapi/reporting/ticketlanguagecountinfo, POST /openapi/reporting/ticketscalculation, POST /openapi/reporting/ticketsperintegration, POST /openapi/reporting/ticketsperlabels, POST /openapi/reporting/ticketspermarketplace, POST /openapi/reporting/ticketsperproduct, POST /openapi/reporting/ticketspertimereport, GET /openapi/reporting/ticketstatisticcsv, GET /openapi/reporting/ticketswithanswer, POST /openapi/reporting/topsellingproducts, POST /openapi/reporting/useractionscount, POST /openapi/reporting/useraveragetimeinfo, POST /openapi/reporting/userchatsactioncountperday, POST /openapi/reporting/userchatsactionscount, POST /openapi/reporting/userchatsaveragetimeinfo, POST /openapi/reporting/userperformance, POST /openapi/reporting/userschatmessagesgeneralinfo, POST /openapi/reporting/userschatmessagesquantitybyhours, POST /openapi/reporting/usersgeneralchatscount, POST /openapi/reporting/usersgeneralticketscount, POST /openapi/reporting/usersmessagesgeneralinfo, POST /openapi/reporting/usersmessagesquantitybyhours, POST /openapi/reporting/usersresolvetimeinfo, POST /openapi/reporting/usersticketsactionscount, POST /openapi/reporting/useruseractioncountperday, POST /openapi/signature, PUT /openapi/signature/{id}, POST /openapi/support/create-ticket, POST /openapi/support/feature-requests, POST /openapi/template, PUT /openapi/template/{id}, POST /openapi/thread/assignuser, GET /openapi/thread/bycontact/{customerId}, POST /openapi/thread/changestarred/{value}, POST /openapi/thread/create, PUT /openapi/thread/draft/{threadId}, POST /openapi/thread/markresolved, POST /openapi/thread/markunresolved, POST /openapi/thread/merge, POST /openapi/thread/note/{threadId}, POST /openapi/thread/snooze, POST /openapi/thread/snoozethread, POST /openapi/thread/ticketsforreading/paged, POST /openapi/user/simple_paged
401	User is not authenticated or authorized; Unauthorized; Authentication failed (wrong password, expired token, etc.); User is not authenticated or authorized.; Missing or invalid authentication token.; User is not authenticated	POST /openapi/account/addcustomintegration, GET /openapi/account/getallcustomintegrations, GET /openapi/account/paged, PUT /openapi/account/updatecustomintegration, GET /openapi/account/{id}, DELETE /openapi/account/{id}, POST /openapi/auth/token, GET /openapi/autoresponder, POST /openapi/autoresponder, GET /openapi/autoresponder/{id}, PUT /openapi/autoresponder/{id}, GET /openapi/bytefiles/messageattachments/{messageId}, GET /openapi/bytefiles/messageattachments/{messageId}/links, GET /openapi/bytefiles/paged, GET /openapi/bytefiles/{id}, POST /openapi/chat/assignuser/{chatId}/{userId}, DELETE /openapi/chat/assignuser/{chatId}/{userId}, GET /openapi/chat/chatsbycustomer/{customerId}, GET /openapi/chat/customer/{chatId}, DELETE /openapi/chat/customer/{chatId}, POST /openapi/chat/customer/{chatId}/{customerId}, PUT /openapi/chat/draft/{chatId}, GET /openapi/chat/paged, POST /openapi/chat/paged, GET /openapi/chat/pagedchatmessages/{chatId}, POST /openapi/chat/sendmessage, POST /openapi/chat/status/{chatId}/{status}, GET /openapi/chat/{id}, POST /openapi/customer, GET /openapi/customer/paged, GET /openapi/customer/{id}, POST /openapi/feedback/paged, GET /openapi/folder, GET /openapi/folder/{id}, POST /openapi/folderthreads/assignfolderstothreads, DELETE /openapi/folderthreads/deletefolderfromthread, POST /openapi/folderthreads/removefoldersfromthreads, GET /openapi/message/pagedthreadmessages/{threadId}, POST /openapi/message/send, GET /openapi/message/threadmessages/{threadId}, GET /openapi/messagerule, POST /openapi/messagerule, GET /openapi/messagerule/{id}, PUT /openapi/messagerule/{id}, GET /openapi/messagetranslate/paged, GET /openapi/messagetranslate/{id}, POST /openapi/order, GET /openapi/order/paged, GET /openapi/order/{id}, GET /openapi/prioritysla/paged, GET /openapi/prioritysla/{id}, GET /openapi/reporting/accstats, POST /openapi/reporting/ai/csvreport, POST /openapi/reporting/aiusagebyactiontypes, POST /openapi/reporting/aiusagebyuser, GET /openapi/reporting/alltimestats, POST /openapi/reporting/autoresponsesusage, POST /openapi/reporting/avaragetimeinfo, GET /openapi/reporting/billingchatsperchannel, GET /openapi/reporting/billinggeneral, GET /openapi/reporting/billingticketperchannel, GET /openapi/reporting/byuser, POST /openapi/reporting/casescalculation, POST /openapi/reporting/casesstatusesinfo, POST /openapi/reporting/comparecreatedansweredresolved, POST /openapi/reporting/countrieslist, POST /openapi/reporting/dueoverduecountinfo, POST /openapi/reporting/dueoverduepercentageinfo, POST /openapi/reporting/instantmessageschatscount, POST /openapi/reporting/instantmessageschatsperaccount, POST /openapi/reporting/instantmessageschatspermarketplace, POST /openapi/reporting/instantmessagesoverview, POST /openapi/reporting/instantmessagesuserperformance, POST /openapi/reporting/itemssoldineachchannel, POST /openapi/reporting/messagescountinfo, POST /openapi/reporting/moneyfromeachchannel, POST /openapi/reporting/notsentmessagescount, POST /openapi/reporting/productsearnedmoney, POST /openapi/reporting/templatesusage, POST /openapi/reporting/ticketlanguagecountinfo, POST /openapi/reporting/ticketscalculation, POST /openapi/reporting/ticketsperintegration, POST /openapi/reporting/ticketsperlabels, POST /openapi/reporting/ticketspermarketplace, POST /openapi/reporting/ticketsperproduct, GET /openapi/reporting/ticketspertime, POST /openapi/reporting/ticketspertimereport, GET /openapi/reporting/ticketstatisticcsv, GET /openapi/reporting/ticketswithanswer, GET /openapi/reporting/todaystats, POST /openapi/reporting/topsellingproducts, POST /openapi/reporting/useractionscount, POST /openapi/reporting/useraveragetimeinfo, POST /openapi/reporting/userchatsactioncountperday, POST /openapi/reporting/userchatsactionscount, POST /openapi/reporting/userchatsaveragetimeinfo, POST /openapi/reporting/userperformance, POST /openapi/reporting/userschatmessagesgeneralinfo, POST /openapi/reporting/userschatmessagesquantitybyhours, POST /openapi/reporting/usersgeneralchatscount, POST /openapi/reporting/usersgeneralticketscount, POST /openapi/reporting/usersmessagesgeneralinfo, POST /openapi/reporting/usersmessagesquantitybyhours, POST /openapi/reporting/usersresolvetimeinfo, POST /openapi/reporting/usersticketsactionscount, POST /openapi/reporting/useruseractioncountperday, GET /openapi/signature, POST /openapi/signature, GET /openapi/signature/{id}, PUT /openapi/signature/{id}, POST /openapi/support/create-ticket, POST /openapi/support/feature-requests, GET /openapi/task/paged, GET /openapi/task/{id}, GET /openapi/template, POST /openapi/template, GET /openapi/template/paged, GET /openapi/template/term, GET /openapi/template/{id}, PUT /openapi/template/{id}, GET /openapi/thread/assignpriority/{threadId}/{id}, POST /openapi/thread/assignuser, GET /openapi/thread/bycontact/{customerId}, GET /openapi/thread/byfeedback/{feedbackId}, GET /openapi/thread/byorder/{orderId}, GET /openapi/thread/byproduct/{productVariationId}, POST /openapi/thread/changestarred/{value}, POST /openapi/thread/create, PUT /openapi/thread/draft/{threadId}, POST /openapi/thread/markresolved, POST /openapi/thread/markunresolved, POST /openapi/thread/merge, POST /openapi/thread/note/{threadId}, GET /openapi/thread/parentthread/{id}, POST /openapi/thread/removeorder/{threadId}, GET /openapi/thread/simplifiedthread/{id}, POST /openapi/thread/snooze, POST /openapi/thread/snoozethread, GET /openapi/thread/threadscount, POST /openapi/thread/ticketsforreading/paged, GET /openapi/thread/unresolvedticketsassignedusers, GET /openapi/threadattachment/paged, GET /openapi/threadattachment/{id}, GET /openapi/user/id_name, GET /openapi/user/me, POST /openapi/user/simple_paged
403	User does not have permission to create integrations; User does not have permission to view integrations; User does not have permission to update integrations; User does not have permission to delete integrations; User does not have the Feedbacks view permission; User does not have access to this thread; User does not have permission to send messages to this thread; User does not have permission to view templates; User does not have permission to create threads; User does not have permission to view company users	POST /openapi/account/addcustomintegration, GET /openapi/account/getallcustomintegrations, PUT /openapi/account/updatecustomintegration, DELETE /openapi/account/{id}, POST /openapi/feedback/paged, GET /openapi/message/pagedthreadmessages/{threadId}, POST /openapi/message/send, GET /openapi/message/threadmessages/{threadId}, GET /openapi/template, GET /openapi/template/term, POST /openapi/thread/create, GET /openapi/thread/simplifiedthread/{id}, GET /openapi/user/id_name, POST /openapi/user/simple_paged
404	Integration with the specified ID was not found; No autoresponder with the given id exists.; Message with the specified ID was not found; Chat or user ID was not found; Customer with the specified ID was not found; Chat or customer ID was not found; Chat with the specified ID was not found; No such folder is available to the current user.; Association not found; Thread with the specified ID was not found; No rule with the given id exists.; No such signature belongs to the current user.; No template with the given id exists.; Thread or priority ID was not found; User ID or one or more thread IDs were not found; Feedback with the specified ID was not found; Order with the specified ID was not found; Product variation with the specified ID was not found; One or more thread IDs were not found; Child thread with the specified ID was not found	PUT /openapi/account/updatecustomintegration, DELETE /openapi/account/{id}, GET /openapi/autoresponder/{id}, PUT /openapi/autoresponder/{id}, GET /openapi/bytefiles/messageattachments/{messageId}/links, POST /openapi/chat/assignuser/{chatId}/{userId}, DELETE /openapi/chat/assignuser/{chatId}/{userId}, GET /openapi/chat/chatsbycustomer/{customerId}, GET /openapi/chat/customer/{chatId}, DELETE /openapi/chat/customer/{chatId}, POST /openapi/chat/customer/{chatId}/{customerId}, PUT /openapi/chat/draft/{chatId}, GET /openapi/chat/pagedchatmessages/{chatId}, POST /openapi/chat/sendmessage, POST /openapi/chat/status/{chatId}/{status}, GET /openapi/folder/{id}, DELETE /openapi/folderthreads/deletefolderfromthread, GET /openapi/message/pagedthreadmessages/{threadId}, POST /openapi/message/send, GET /openapi/message/threadmessages/{threadId}, GET /openapi/messagerule/{id}, PUT /openapi/messagerule/{id}, GET /openapi/signature/{id}, PUT /openapi/signature/{id}, PUT /openapi/template/{id}, GET /openapi/thread/assignpriority/{threadId}/{id}, POST /openapi/thread/assignuser, GET /openapi/thread/bycontact/{customerId}, GET /openapi/thread/byfeedback/{feedbackId}, GET /openapi/thread/byorder/{orderId}, GET /openapi/thread/byproduct/{productVariationId}, POST /openapi/thread/changestarred/{value}, PUT /openapi/thread/draft/{threadId}, POST /openapi/thread/markresolved, POST /openapi/thread/markunresolved, POST /openapi/thread/merge, POST /openapi/thread/note/{threadId}, GET /openapi/thread/parentthread/{id}, POST /openapi/thread/removeorder/{threadId}, GET /openapi/thread/simplifiedthread/{id}, POST /openapi/thread/snooze, POST /openapi/thread/snoozethread
429	Too many authentication attempts, please try again later	POST /openapi/auth/token
502	The support service is unavailable; the ticket was not created. Try again later.; The roadmap service is unavailable; the feature request was not created. Try again later.	POST /openapi/support/create-ticket, POST /openapi/support/feature-requests

Related

• Troubleshooting: the errors integrators meet most, and what to do about each.
• Authentication: what 400 means on sign-in, and 401 and 403.
• API reference: the responses each operation documents.