Reference
Errors and limits Beta
On this page
When a request fails, the API answers with an HTTP status and a JSON error body. This page lists the error codes, the rate limits and when to retry a request.
The error body
{
"error": {
"code": "channel_access_denied",
"message": "You do not have access to one of the channels",
"requestID": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}
| Field | Description |
|---|---|
code | What went wrong. Codes are stable, so your code can rely on them. |
message | An English description for people. It can change, so don’t parse it. |
param | The request parameter or body field at fault, when there is one. A field inside the body is named with dots, as in endpoints.1.channelID. |
requestID | Our ID for the request. Quote it when you contact support. |
The token endpoint uses the OAuth error body instead. See Token errors.
A path that the API doesn’t serve returns 404 with a different body. A path it serves, called with the wrong method, returns 405 with a plain-text body. Check the method and the path.
Error codes
These codes can come from any endpoint.
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_request | The request is malformed. A parameter or field is missing or has the wrong value. param names it when it can. |
| 401 | invalid_token | The token is missing, malformed or expired. The key may be revoked or expired. The token may have been sent to a host other than api.conclude.io. Get a new token. If that fails, check the key. |
| 403 | insufficient_scope | The key doesn’t have a scope this endpoint needs. The message names the scopes that work. |
| 403 | forbidden | The person the token acts for doesn’t have the access or permission this request needs. |
| 403 | plan_limit | Your organization’s plan has no room for another channel connection, or doesn’t include chats or bridges. param names the limit. |
| 404 | not_found | The resource doesn’t exist, or the person the token acts for can’t see it. |
| 409 | conflict | The request conflicts with the current state. |
| 410 | gone | The resource has been deleted, for example your organization. |
| 429 | rate_limited | The key made too many requests. See Rate limits. |
| 500 | internal_error | Something went wrong on our end. The message doesn’t say what. Quote the requestID if you contact support. |
| 503 | unavailable | Conclude couldn’t finish the request. Try again. |
These codes come from the requests on the Connections page.
| Status | Code | Meaning |
|---|---|---|
| 400 | channel_not_connectable | The channel can’t be connected. It is archived or deleted, or it is not a regular channel. |
| 403 | subject_required | A key that acts as Conclude sent no subject to a request that needs one, such as a change to a connection or a chat. Ask for a token with a subject. |
| 403 | conclude_not_in_channel | A key that acts as Conclude named a channel that Conclude doesn’t reach. Add Conclude to the channel first. In Microsoft Teams, install the Conclude app in the team. |
| 403 | channel_access_denied | The person the token acts for can’t access the channel. |
| 409 | connections_disabled | Channel connections are turned off for your organization. An admin can turn them on. |
| 409 | already_connected | The channel is already in a connection. A channel can be in only one. |
These codes come from the requests on the Chats page.
| Status | Code | Meaning |
|---|---|---|
| 400 | chat_member_not_allowed | Microsoft Teams wouldn’t add a member, or a member doesn’t have Chat access on the bridge. param names the member when Conclude knows which one. |
| 403 | bridge_chat_not_allowed | The person the token acts for doesn’t have Chat access on the bridge. |
| 409 | chat_needs_two_workspaces | Your organization doesn’t have two workspaces to chat across. |
| 409 | teams_license_missing | None of the Microsoft Teams accounts that Conclude can use has a Teams license. |
| 409 | teams_sign_in_required | Microsoft Teams needs a member, or the integration account, to be signed in to Conclude. |
| 409 | bridge_not_active | An admin has paused the bridge. |
| 409 | bridge_chat_unsupported | The chat is with another organization. Such a chat can only be read and closed. |
Rate limits
- Each key can make at least 25 requests a second, with bursts of up to 50
- The token endpoint accepts 60 requests a minute from one IP address
Above the limit, Conclude answers 429 with a Retry-After header. It gives the number of seconds to wait before you try again. Requests to the token endpoint also count toward a general limit for each IP address and user agent, with bursts of up to 50. Above it, the token endpoint answers 429 with the API’s error body rather than the OAuth error body.
Retries
Retry a request after these errors:
429: wait for the seconds inRetry-After503: try again after a short wait500on aGET: try again after a short wait. If it keeps failing, contact support with therequestID
A write that failed with a network error or a 500 may still have taken effect. Check before you send it again. For example, look the channel up with GET /v1/findChannel and read connected. A repeated create answers already_connected when the first one succeeded.
Don’t retry other 4xx errors unchanged. Fix the request first.