API Errors and Limits

An API error is a response where Chatterfy explains why it didn't complete a request. All errors look the same, so you can figure them out using two fields: the response code and code . This article e

Updated November 2, 20267 min

An API error is a response where Chatterfy explains why it didn't complete a request. All errors look the same, so you can figure them out using two fields: the response code and code.

This article explains how to read an error, what to do about each one, how many requests you can send, and what other API limits there are.

What an error looks like

An API error arrives in JSON with an error object: it contains type, code, message, and request_id. The HTTP response code shows the error group, and code shows the exact reason:

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_limit",
    "message": "limit must not exceed 100",
    "request_id": "req_19b1e1109b0d37e463f571b01c2b5eba"
  }
}

Field	What it is
`type`	The error group, for example `invalid_request_error` or `authentication_error`
`code`	A short name for the specific error. Use it to find a solution in the tables below
`message`	A human-readable explanation. The wording may change, so it's better for your program to look at `code`
`request_id`	The request number. It is included in every response, including successful ones, in the `X-Request-Id` header

When writing to support, include the request_id

With the request_id, support can find your request in seconds. Add the request time and the address you sent it to. Do not send the key itself.

Quick diagnosis: 400, 401, 403, 404

Response code	What happened	What to do
`400`	Error in the request: wrong field, wrong format, incorrect filter	Read the `message` — it explains what is wrong. Fix the request body
`401`	Missing key, invalid key, or it has already been replaced	Check the key and the `ApiKey` header
`403`	The key is working, but there is no access: the role lacks the required permission, or the object is in another company or Space to which the account has not been added	Grant the service account a role with the required permission — API Key Permissions: Which Role to Assign
`404`	The object with this ID does not exist	Check the ID — get it only from API responses

Quick diagnostics: 405, 409, 429, 500, 503

Response code	What happened	What to do
`405`	The address does not have this method	Check the method: `GET`, `POST`, `PATCH`, or `DELETE`
`409`	The action conflicts with the current state	See the `code` in the table below
`429`	Too many requests	Wait for the number of seconds specified in `Retry-After`
`500`, `503`	Failure on the Chatterfy side	Try again in a few seconds. If this doesn't help, contact support with the `request_id`

Key and access errors: 401 and 403

`code`	What it means	What to do
`missing_api_key`	Header `ApiKey` not provided	Добавьте заголовок `ApiKey: ВАШ_КЛЮЧ`. Заголовок `Authorization` не подходит
`invalid_api_key`	Key is incorrect, truncated, or already replaced	Copy the entire key again. If the key was changed using the Reissue key button, insert the new one — How to get an API key
`access_denied`	The role lacks permission for this action	Check the permissions table in the article API Key Permissions: Which Role to Assign
`permissions_unavailable`	Failed to verify permissions — temporary failure	Retry the request in a few seconds

Request body errors: 400

400 errors due to the request body: it is empty, not JSON, too large, or a field failed validation.

`code`	What it means	What to do
`empty_body`	Request body is empty	Pass JSON, at least `{}`
`invalid_body`	Body is not JSON, is malformed JSON, or a field has the wrong type, for example text instead of a number	Check quotes and commas. Keys and strings must use double quotes only
`body_too_large`	Body is larger than 64 KB	Reduce the request, for example, split the filter
`validation_failed`	Field failed validation: wrong format, incorrect value, or too long	The `message` specifies which field is incorrect and why
`missing_anchor`	Required ID not provided: `bot_id`, `chat_id`, or `company_id`	Add the required ID to the request body
`no_fields`	No fields provided in `PATCH`	Provide at least one field for modification
`empty_message`	Message without text and without files	Provide `content`, `files`, or both

Pagination, export, and period errors: 400

400 errors during pagination (limit, cursor), chat export, and period analytics requests:

`code`	Meaning	What to do
`invalid_limit`	`limit` is less than 1 or greater than 100	Specify a `limit` between 1 and 100
`invalid_cursor`	`cursor` is corrupted or manually constructed	Pass `next_cursor` from the response unchanged
`cursor_out_of_range`	Search reached the 10,000th chat	Use export — How to export all chats via API — or split the list using a filter by `created_at`
`cursor_expired`	More than 5 minutes have passed between export pages	Restart the export without `cursor`
`invalid_range`, `range_too_wide`	In analytics, `to` is earlier than `from` or the period is longer than 366 days	Correct the period dates
`invalid_timezone`	Unknown time zone	Specify a name like `Europe/Moscow`

Chat filter errors: 400

Filter error codes start with invalid_filter_ or unknown_filter_. The message field indicates the error location, for example filter.filters[1] — this is the second condition in the group (counting starts from zero).

`code`	Meaning
`unknown_filter_field`	This field does not exist. The `message` lists all available ones
`invalid_filter_operator`	The field does not support this operator. The `message` lists the suitable ones
`invalid_filter_value`	Incorrect value type: string instead of list, text instead of number, invalid date
`invalid_filter_key`	For `custom_fields` and `tracker_fields`, the `key` was not provided, or an incorrect field id was passed
`invalid_filter_node`	Condition and group are mixed up: one node contains both `field` and `filters`
`filter_too_large`, `filter_too_deep`	More than 64 conditions or more than 5 levels of nesting

All fields and operators are in the article Chat filters in the API.

Errors in foreign IDs: tag, field, assignee

`code`	What it means	What to do
`unknown_tag`	Tag belongs to a different bot	Take tag IDs from `GET /bots/v1/{bot_id}/tags` of this bot
`unknown_custom_field`	Field belongs to a different bot or a `key` was passed instead of an ID	Get the ID from `GET /bots/v1/{bot_id}/custom-fields`
`unknown_assignee`	The person is not a member of this bot's Space	Select a member from `POST /spaces/v1/{space_id}/members/search`
`unknown_reply_message`	Reply message is from a different chat	Provide the message ID from the same chat
`..._not_found`	Object not found: `chat_not_found`, `bot_not_found`, `message_not_found`, and others	Check the key's ID and permissions
`unknown_endpoint`	This address does not exist	Check the address: the version comes after the resource, for example `/chats/v1/search`

Conflicts: error 409

`code`	Meaning
`space_not_empty`	A Space cannot be deleted while it contains bots
`domain_already_exists`	This domain is already registered on the platform
`domain_blocked`	A blocked domain cannot be modified or deleted

Request limit: 120 per minute and error 429

Each key can send 120 requests per minute. The limit is calculated over the last 60 seconds, not by calendar minutes. The exact value for your key is visible in the API key column on the Service accounts page.

Each response includes headers that show how many are remaining:

Header	Meaning
`X-RateLimit-Limit`	How many requests per minute are allowed for this key
`X-RateLimit-Remaining`	How many requests are still remaining
`X-RateLimit-Reset`	When the limit will reset — time in Unix seconds
`Retry-After`	Only in a `429` response: how many seconds to wait

If you receive 429 rate_limit_exceeded — wait Retry-After seconds and continue. Do not repeat the request immediately: the limit will not recover faster from that.

Other API limits

What	Limit
Request body size	64 KB
Header size	16 KB
Response time	If Chatterfy does not respond within 10 seconds, you will receive a `503 service_unavailable`
Records per page	Up to 100, default is 25
Chat search depth	10,000 chats. For more, use export
Export cursor	5 minutes after each page
Analytics period	Up to 366 days
Message text	Up to 4096 characters
Attachments in message	Up to 10

FAQ

API Key Permissions: Which Role to Assign

API key permissions define what an application is allowed to do in Chatterfy. They depend on two service account roles: the company role and the role in each Space. This article explains which role to

How to get an API key

An API key is a password that your program uses to log into Chatterfy. The key is not issued to you personally, but to a service account — a separate company member specifically for integrations. You

Chat filters in the API

Chat filters are conditions used by the API to select chats: for example, 'unread', 'with the tag Paid', or 'came from Google'. The same filter works in search, counting, exporting, and event subscrip

First API request in 5 minutes

The first API request is a check that the key works. You will send a request to Chatterfy and receive your company in the response. Next, step-by-step, you will find the company, bot, and chat IDs — t

Was this article helpful?

API Errors and Limits

What an error looks like

Quick diagnosis: 400, 401, 403, 404

Quick diagnostics: 405, 409, 429, 500, 503

Key and access errors: 401 and 403

Request body errors: 400

Pagination, export, and period errors: 400

Chat filter errors: 400

Errors in foreign IDs: tag, field, assignee

Conflicts: error 409

Request limit: 120 per minute and error 429

Other API limits

FAQ

Can I increase the request limit?

Are limits shared between keys?

Why does the API return 404 even though the object definitely exists?

Should I repeat the request after a 503 error?

What should I do if the error is not in the list?

Related