The API returns HTTP responses on each request to indicate the success or otherwise of API requests. The codes listed below are often used, and the API may use others. Note that 4xx and 5xx responses may be returned for any request and clients should cater for them.
| Response Code | Description |
|---|---|
| 400 | Bad Request -- General client error, possibly malformed data. A request body that is not valid JSON also returns 400, usually with the error code parameter_invalid. |
| 401 | Unauthorized -- The API Key was not authorised (or no API Key was found). |
| 403 | Forbidden -- The request is not allowed. If the API or feature is not available on your current plan or workspace, the error code is api_plan_restricted. |
| 404 | Not Found -- The resource was not found. A request using an HTTP method that the endpoint does not support also returns 404, or 406 if the Accept header is missing or does not include a media type the endpoint returns (usually application/json). |
| 405 | Method Not Allowed -- The action is not allowed for this type of admin. |
| 406 | Not Acceptable -- The resource cannot return the client's required content type. |
| 408 | Request Timeout -- The server would not wait any longer for the client. |
| 409 | Conflict - Multiple existing users match this email address - must be more specific using user_id |
| 422 | Unprocessable Entity -- The data was well-formed but invalid. |
| 429 | Too Many Requests -- The client has reached or exceeded a rate limit, or the server is overloaded. |
| 500, 502, 503, 504 | Server errors - something went wrong with Intercom's servers. These responses are most likely momentary operational errors (e.g. temporary unavailability), and, as a result, requests should be retried once. |
Most responses to authenticated requests include the following headers:
Intercom-Version: the API version used to process the request. This is the version you sent in theIntercom-Versionrequest header or, if you did not send one, the default version set for your app. It is not returned on authentication errors, on429errors with the coderate_limit_exceeded, or when theIntercom-Versionheader you sent is not a valid version.X-RateLimit-Limit,X-RateLimit-RemainingandX-RateLimit-Reset: your app's rate limit for the current 10-second window, how many requests are left in it, and when it resets. These headers are not sent when the request has no valid credentials. They are described in Rate Limiting.
Some 429 responses, such as when a conversation is receiving new parts too quickly, also include a Retry-After header with the number of seconds to wait before retrying.