# Ошибки

Категории ошибок и ошибки, специфичные для A2A

> Страница сайта A2A Docs — неофициального перевода документации протокола Agent2Agent (https://a2adocs.ru/protocol/errors/). Тип: Перевод. Основа: Спецификация, раздел 3.3.2; What's New (https://a2a-protocol.org/latest/specification/#332-error-handling). Версия спецификации 1.0.0, сверено 05.10.2026.

Любая операция может вернуть ошибку. Серверы ДОЛЖНЫ возвращать подходящие ошибки и СЛЕДУЕТ давать полезную информацию, которая помогает клиентам устранить проблему.

## Категории ошибок

| Категория | Требования к серверу | Примеры кодов | Типичные сценарии |
| --- | --- | --- | --- |
| Аутентификация: неверные или отсутствующие учётные данные | ДОЛЖЕН отклонять запросы с неверными или отсутствующими учётными данными. СЛЕДУЕТ включать в ответ сведения о вызове аутентификации и указывать нужную схему. | HTTP `401 Unauthorized`, gRPC `UNAUTHENTICATED`, особая ошибка JSON-RPC | Нет bearer-токена, истёк API-ключ, неверный токен OAuth. |
| Авторизация: недостаточно прав | ДОЛЖЕН вернуть ошибку авторизации, если у аутентифицированного клиента не хватает прав. СЛЕДУЕТ указывать, какого права или scope не хватает, не раскрывая сведений о недоступных ресурсах. НЕ ДОЛЖЕН раскрывать существование ресурсов, к которым у клиента нет доступа. | HTTP `403 Forbidden`, gRPC `PERMISSION_DENIED`, особая ошибка JSON-RPC | Попытка получить задачу другого пользователя, недостаточные scope OAuth. |
| Валидация: неверные параметры или формат | ДОЛЖЕН проверять все входные параметры до обработки. СЛЕДУЕТ указывать, какие параметры не прошли проверку и почему, и подсказывать допустимые значения или форматы. | HTTP `400 Bad Request`, gRPC `INVALID_ARGUMENT`, JSON-RPC `-32602 Invalid params` | Неверный формат идентификатора задачи, нет обязательных частей сообщения, неподдерживаемый тип содержимого. |
| Ресурсы: задача не найдена или недоступна | ДОЛЖЕН вернуть «не найдено», если ресурса нет или он недоступен аутентифицированному клиенту. НЕ СЛЕДУЕТ различать «не существует» и «нет доступа», чтобы не допустить утечки информации. | HTTP `404 Not Found`, gRPC `NOT_FOUND`, особая ошибка JSON-RPC | Идентификатора задачи нет, задача удалена, настройка не найдена. |
| Системные: внутренний сбой или временная недоступность | СЛЕДУЕТ возвращать разные коды для временных и постоянных сбоев. МОЖЕТ давать рекомендации по повтору (например, заголовок `Retry-After` в HTTP). СЛЕДУЕТ записывать системные ошибки в журнал. | HTTP `500` или `503`, gRPC `INTERNAL` или `UNAVAILABLE`, JSON-RPC `-32603 Internal error` | Сбой соединения с базой данных, таймаут нижестоящего сервиса, превышение лимита запросов. |

## Структура ошибки

Все ответы с ошибкой в протоколе A2A, независимо от привязки, ДОЛЖНЫ передавать:

1. **Код ошибки.** Машиночитаемый идентификатор типа ошибки: строковый или числовой код либо статус, принятый в протоколе.
2. **Сообщение об ошибке.** Описание, понятное человеку.
3. **Подробности** (необязательно). Массив объектов с дополнительной структурированной информацией. Каждый объект ДОЛЖЕН содержать ключ `@type`, определяющий тип объекта (представление `Any` из ProtoJSON). Где это уместно, СЛЕДУЕТ использовать типы из модели ошибок `google.rpc`, например `ErrorInfo` и `BadRequest`. В подробностях можно указать затронутые поля, контекст (идентификатор задачи, время) и подсказки по устранению.

Привязки ДОЛЖНЫ отображать эти элементы в свои родные представления ошибок, сохраняя смысл.

## Ошибки A2A

| Ошибка | Описание |
| --- | --- |
| `TaskNotFoundError` | Указанный идентификатор не соответствует существующей или доступной задаче. Он может быть неверным, истёкшим или относиться к завершённой и удалённой задаче. |
| `TaskNotCancelableError` | Попытка отменить задачу, которую отменить нельзя: она уже в конечном состоянии (`TASK_STATE_COMPLETED`, `TASK_STATE_FAILED`, `TASK_STATE_CANCELED`, `TASK_STATE_REJECTED`). |
| `PushNotificationNotSupportedError` | Клиент пытается использовать push-уведомления, но агент их не поддерживает (`AgentCard.capabilities.pushNotifications` равно `false`). |
| `UnsupportedOperationError` | Запрошенная операция или её отдельный аспект не поддерживается этой реализацией агента. |
| `ContentTypeNotSupportedError` | Тип содержимого в частях сообщения или предполагаемый для артефакта не поддерживается агентом или конкретным навыком. |
| `InvalidAgentResponseError` | Агент вернул ответ, не соответствующий спецификации для текущего метода. |
| `ExtendedAgentCardNotConfiguredError` | У агента нет расширенной Agent Card, хотя она требуется для запрошенной операции. |
| `ExtensionSupportRequiredError` | Сервер потребовал использовать расширение с `required: true` из Agent Card, но клиент не заявил его поддержку в запросе. |
| `VersionNotSupportedError` | Версия протокола, указанная в запросе (параметром `A2A-Version`), не поддерживается агентом. |

## Модель ошибок в версии 1.0

В версии 1.0 ошибки приведены к ProtoJSON-представлению `google.rpc.Status` вместо RFC 9457 (Problem Details). Для JSON-RPC и HTTP+JSON действует единое правило:

- в `details` (в JSON-RPC это поле `data`) ДОЛЖЕН быть объект `google.rpc.ErrorInfo`;
- в нём поле `reason` содержит тип ошибки A2A в формате UPPER_SNAKE_CASE (например, `TASK_NOT_FOUND`);
- поле `domain` равно `a2a-protocol.org`;
- тип содержимого HTTP+JSON-ответа с ошибкой теперь `application/json`, а не `application/problem+json`.

Пример для JSON-RPC (со страницы «What's New»):

```json
"error": {
  "code": -32001,
  "message": "Task not found",
  "data": [
    {
      "@type": "type.googleapis.com/google.rpc.ErrorInfo",
      "reason": "TASK_NOT_FOUND",
      "domain": "a2a-protocol.org",
      "metadata": { "taskId": "123" }
    }
  ]
}
```

Пример для HTTP+JSON:

```http
HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": {
    "code": 404,
    "status": "NOT_FOUND",
    "message": "The specified task ID does not exist",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "TASK_NOT_FOUND",
        "domain": "a2a-protocol.org"
      }
    ]
  }
}
```

Соответствие ошибок конкретным кодам привязок смотрите в разделах 5.4, 9.5, 10.6 и 11.6 оригинала.