Коды ошибок (V2 и ACP)

В V2 и ACP все ошибки возвращаются в формате:

{
  "time": 1700000000,
  "error": {
    "code": "string",
    "http_status": 400,
    "message": "string",
    "details": { "key": "value" }
  }
}

• code: машинночитаемый код.
• http_status: HTTP-статус ответа.
• message: краткое описание.
• details: опциональные детали (валидатор, поля и т.п.).

Источники:

• интерфейс ошибок API: interfaces/api/apierrors/app_error.go
• маппинг доменных ошибок: interfaces/api/apierrors/mapper.go
• доменные коды: domain/errors/errors.go

Стандартные ошибки API (apierrors)

code	http_status	message
auth.unauthorized	401	Unauthorized
auth.invalid_headers	400	Invalid headers
auth.invalid_token	401	Invalid token
auth.client_version_too_low	400	Client version too low
auth.banned	403	User is banned
auth.forbidden	403	Forbidden
validation.invalid_input	422	Invalid input
validation.conflict	409	Conflict
system.internal	500	Internal server error
system.try_again_later	503	Please try again later
db.select_failed	500	Database select failed
db.update_failed	500	Database update failed

Дополнительно при маппинге доменных ошибок:

code	http_status	message	источник
resource.not_found	404	Not found	mapper
system.unsupported	501	Unsupported	mapper

Доменные коды (domain/errors)

Эти коды маппятся в AppError через mapper.go:

domain code	Назначение	Маппинг в API
unauthorized	нет авторизации	auth.unauthorized (401)
forbidden	запрет доступа	auth.forbidden (403)
not_found	ресурс не найден	resource.not_found (404)
invalid	неверные данные	validation.invalid_input (422)
conflict	конфликт состояния	validation.conflict (409)
unsupported	не поддерживается	system.unsupported (501)
internal	внутренняя ошибка	system.internal (500)

Примечание: точный HTTP‑статус выбирается маппером, исходя из доменного кода.

Ошибки version vector (vclock)

Version vector используется для оптимистичного контроля конкурентности при обновлении data пользователя. Ошибки возвращаются в стандартном формате AppError c HTTP 409/422 и details содержащим обе версии:

{
  "time": 1700000000,
  "error": {
    "code": "version.dominated",
    "http_status": 409,
    "message": "Version dominated by server",
    "details": {
      "server_version_vector": { "server": 2, "xxx-device": 3000 },
      "client_version_vector": { "xxx-device": 2999 }
    }
  }
}

code	http_status	описание
version.dominated	409	Сервер имеет более новую версию (incoming ≤ server)
version.concurrent	409	Конфликт: часть полей новее, часть старше
version.server_key_update	409	Клиент пытается инкрементить ключ «server»
version.unparsable	422	Невалидный формат version_vector

V1 маппинг: в V1 API те же ошибки возвращаются через числовые статус-коды:

V1 status	code	описание
3001	ErrorVersionDominated	Сервер доминирует
3002	ErrorVersionConcurrent	Конкурентный конфликт
3003	ErrorVersionInvalid	Невалидный вектор
3004	ErrorVersionServerKeyUpdate	Попытка инкремента ключа «server»
3005	ErrorVersionUnparsable	Невозможно распарсить