Errors

AAP defines a single typed error payload (aap.error) that every dealer agent MUST use when a skill cannot be fulfilled. The error rides inside the standard A2A error envelope: error.data for JSON-RPC (Section 9.5) or as a DataPart in a non-2xx HTTP response for HTTP+JSON (Section 11.6).

Error payload shape

{
  "type": "aap.error",
  "error_id": "err_01HZ9EXAMPLE",
  "code": "SCHEMA_VALIDATION_FAILED",
  "message": "filters.year_min must be an integer",
  "retryable": false,
  "details": {
    "instancePath": "/filters/year_min",
    "received": "twenty-twenty"
  },
  "created_at": "2026-04-30T10:15:30Z"
}

Field	Type	Required	Description
type	const	yes	Always aap.error.
error_id	string	yes	Unique identifier for this error instance (UUID recommended), suitable for support correlation.
code	enum	yes	One of the 11 AAP error codes below.
message	string	yes	Human-readable error message. May be surfaced to the end user.
retryable	boolean	yes	Whether the buyer agent SHOULD retry the same request after a backoff.
details	object	no	Code-specific details; free shape (e.g. validation paths, retry hints).
created_at	date-time	yes	When the error was generated by the dealer agent.

Error code reference

The 11 codes, their meaning, recommended HTTP status, recommended JSON-RPC code, and retryable default.

code	Meaning	HTTP	JSON-RPC	retryable default
UNSUPPORTED_SKILL	The agent does not implement this skill.	404	-32601 (Method not found)	false
SCHEMA_VALIDATION_FAILED	Request body fails JSON Schema validation.	422	-32602 (Invalid params)	false
MISSING_REQUIRED_FIELD	A specifically required field is absent.	422	-32602 (Invalid params)	false
VEHICLE_NOT_FOUND	The supplied vin / stock / vehicle_id does not match any listing.	404	-32000 (Server error)	false
VEHICLE_UNAVAILABLE	The vehicle exists but is no longer available (e.g. sold).	409	-32000 (Server error)	false
CONTACT_CONSENT_REQUIRED	customer info present without consent, or follow-up channel not in consent.allowed_channels.	403	-32000 (Server error)	false
INVALID_CONSENT	consent is present but malformed, expired, or its scope does not cover the called skill.	403	-32000 (Server error)	false
APPOINTMENT_TIME_UNAVAILABLE	None of the requested windows can be honored AND the dealer has no proposed alternatives.	409	-32000 (Server error)	false
AUTH_REQUIRED	Bearer token missing or invalid.	401	-32001 (Server error reserved)	false
RATE_LIMITED	Client has exceeded the dealer's rate limit.	429	-32002 (Server error reserved)	true
INTERNAL_ERROR	Unhandled dealer-side error.	500	-32603 (Internal error)	true

retryable is a default, not a hard rule. Dealer agents MAY override it per-instance — for example, a SCHEMA_VALIDATION_FAILED is conceptually non-retryable (the request is malformed and a retry will fail identically), but a transient INTERNAL_ERROR is conceptually retryable. Buyer agents MUST honor the value the dealer returns rather than the table default.

Per-code semantics

UNSUPPORTED_SKILL

Returned when a buyer agent calls a skill id the dealer agent does not implement. AAP-compliant dealers implement all seven skills, so this code is rare in practice. It is intended for forward-compat scenarios where future AAP versions add skills not present in v0.1.

SCHEMA_VALIDATION_FAILED

Returned when the request body does not satisfy the AAP request schema (missing type, wrong field types, unknown filter keys, unknown enum values, etc.). details.instancePath SHOULD point at the failing field.

MISSING_REQUIRED_FIELD

Returned when a specifically required field is absent. This overlaps with SCHEMA_VALIDATION_FAILED; dealer agents MAY use either, but MISSING_REQUIRED_FIELD is preferred when the issue is a single missing required field rather than a structural validation problem (e.g. a lead.appointment of type test_drive with no vehicles[]).

VEHICLE_NOT_FOUND

Returned by inventory.vehicle (or by lead.vehicle / lead.appointment when a vehicle reference does not match) when none of the supplied identifiers (vin, stock, vehicle_id, year+make+model) match a listing.

VEHICLE_UNAVAILABLE

Returned when the listing existed but is no longer available — e.g. status changed to "Sold" between an inventory.search snapshot and a follow-up inventory.vehicle call. Buyer agents SHOULD recompute search results and surface the change to the user.

CONTACT_CONSENT_REQUIRED

Returned when a lead.* request includes customer but no consent, or when the consent.allowed_channels[] does not include the channel the dealer's process needs to use for follow-up. See Behavior rules.

INVALID_CONSENT

Returned when consent is structurally present but unusable: e.g. consent.scope[] does not include the required scope (general_inquiry for lead.general, vehicle_inquiry for lead.vehicle, appointment for lead.appointment), or consent.granted_at is in the future, or consent_text is empty.

APPOINTMENT_TIME_UNAVAILABLE

Returned by lead.appointment when none of the user's requested_windows[] can be honored AND the dealer has no proposed_slots to offer. Dealers SHOULD prefer status: "proposed" with alternative slots over this error whenever possible.

AUTH_REQUIRED

Returned when the agent's security_requirements is non-empty and the request is missing a valid Authorization: Bearer <token> header. The buyer agent SHOULD obtain credentials and retry; the error itself is retryable: false because retrying the same unauthenticated request would fail identically.

RATE_LIMITED

Returned when the buyer agent exceeds the dealer's per-key quota. retryable: true is the default. Dealer agents SHOULD include details.retry_after_ms (or details.retry_after_seconds) so the buyer agent can back off appropriately. AAP does not standardize the rate-limit values themselves.

INTERNAL_ERROR

A catch-all for unexpected dealer-side failures. retryable: true is the default; the buyer agent SHOULD retry with exponential backoff. Dealer agents SHOULD set error_id so support tickets can correlate to logs.

Example error payloads

JSON-RPC error response

{
  "jsonrpc": "2.0",
  "id": "req-3",
  "error": {
    "code": -32602,
    "message": "Invalid params: filters.year_min must be an integer",
    "data": {
      "type": "aap.error",
      "error_id": "err_01HZ9EXAMPLE",
      "code": "SCHEMA_VALIDATION_FAILED",
      "message": "filters.year_min must be an integer",
      "retryable": false,
      "details": {
        "instancePath": "/filters/year_min",
        "received": "twenty-twenty"
      },
      "created_at": "2026-04-30T10:15:30Z"
    }
  }
}

HTTP+JSON error response

A2A v1.0 (Section 11.6) uses Google's standard google.rpc.Status shape for HTTP error bodies. AAP places the typed aap.error payload as one of the entries in error.details[], alongside a google.rpc.ErrorInfo entry whose reason carries the AAP code.

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "error": {
    "code": 422,
    "message": "filters.year_min must be an integer",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "SCHEMA_VALIDATION_FAILED",
        "domain": "autoagentprotocol.org",
        "metadata": {
          "instancePath": "/filters/year_min",
          "received": "twenty-twenty"
        }
      },
      {
        "@type": "type.googleapis.com/aap.error",
        "type": "aap.error",
        "error_id": "err_01HZ9EXAMPLE",
        "code": "SCHEMA_VALIDATION_FAILED",
        "message": "filters.year_min must be an integer",
        "retryable": false,
        "details": {
          "instancePath": "/filters/year_min",
          "received": "twenty-twenty"
        },
        "created_at": "2026-04-30T10:15:30Z"
      }
    ]
  }
}

Consent-required example

A lead.vehicle request with customer but no consent:

{
  "type": "aap.error",
  "error_id": "err_01HZ9CONSENT01",
  "code": "CONTACT_CONSENT_REQUIRED",
  "message": "Customer info present but no ConsentGrant. Provide a 'consent' block with scope including 'vehicle_inquiry'.",
  "retryable": false,
  "details": {
    "missing": "consent",
    "expected_scope": "vehicle_inquiry"
  },
  "created_at": "2026-04-30T10:15:45Z"
}

Rate-limit example

{
  "type": "aap.error",
  "error_id": "err_01HZ9RATE01",
  "code": "RATE_LIMITED",
  "message": "Per-key rate limit exceeded.",
  "retryable": true,
  "details": {
    "retry_after_ms": 30000
  },
  "created_at": "2026-04-30T10:16:00Z"
}

What dealer agents MUST and MUST NOT do

• Dealer agents MUST return errors using this schema (typed aap.error payload), not free-text messages.
• Dealer agents MUST NOT leak internal stack traces in message. Use details for structured diagnostic information that is safe to display.
• Dealer agents MUST set retryable truthfully. Buyer agents follow this signal to decide whether to retry.