Ошибки — A2A Docs

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

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

Категория	Требования к серверу	Примеры кодов	Типичные сценарии
Аутентификация: неверные или отсутствующие учётные данные	ДОЛЖЕН отклонять запросы с неверными или отсутствующими учётными данными. СЛЕДУЕТ включать в ответ сведения о вызове аутентификации и указывать нужную схему.	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, независимо от привязки, ДОЛЖНЫ передавать:

Код ошибки. Машиночитаемый идентификатор типа ошибки: строковый или числовой код либо статус, принятый в протоколе.
Сообщение об ошибке. Описание, понятное человеку.
Подробности (необязательно). Массив объектов с дополнительной структурированной информацией. Каждый объект ДОЛЖЕН содержать ключ @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 оригинала.