Ошибки

Один JSON-формат на все 4xx/5xx публичного API. Старое поле error сохранено.

Формат

4xxJSON

{
  "error": "channel is required",
  "type": "invalid_request_error",
  "code": "validation_error",
  "message": "channel is required",
  "request_id": "0f2c9a…",
  "docs_url": "https://docs.sapportly.pro/docs/api/errors#validation_error"
}

error = message для старых клиентов. Новые клиенты читают message. request_id дублируется в заголовке X-Request-Id.

Коды

code	HTTP	type	Когда
`unauthorized`	401	`authentication_error`	Нет ключа, ключ отозван или неверный.
`forbidden`	403	`permission_error`	Ключ есть, но не хватает scope.
`not_found`	404	`invalid_request_error`	Нет диалога, контакта, вложения.
`validation_error`	400	`invalid_request_error`	Тело или query не прошли проверку.
`rate_limited`	429	`rate_limit_error`	Скользящее окно. Смотрите Retry-After.
`plan_limit_exceeded`	402	`invalid_request_error`	Квота тарифа. Поля resource, used, limit.
`encryption_error`	400	`invalid_request_error`	Не удалось обработать шифрованный payload.
`internal_error`	5xx	`api_error`	Сбой платформы. Можно ретраить.

Лимиты

На успешном ответе: X-RateLimit-Limit, X-RateLimit-Remaining. На 429 ещё Retry-After (секунды). SDK ретраит 429/5xx с jitter и уважает Retry-After.

GET/v1/status

Страница полезна?