Przejdź do treści
Biblioteka skilli
AI i agenci · Budowanie i kod

a2a-error-handling

/a2a-error-handling

Wdraża obsługę błędów A2A: błędy JSON-RPC, kody błędów specyficzne dla A2A, stany awarii zadań i strategie ponownych prób.

Licencja
MIT
Ostatnia zmiana repozytorium
14.09.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
1
Przestarzałość

Brak sygnałów. Repozytorium zmienione 14.09.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Wdraża obsługę błędów A2A: błędy JSON-RPC, kody błędów specyficzne dla A2A, stany awarii zadań i strategie ponownych prób.

Oryginalny opis (EN)

Implement A2A error handling — JSON-RPC errors, A2A-specific error codes, task failure states, retry strategies, and graceful degradation. Use when building robust error handling in A2A agents.

Jak działa

  1. Before writing code
  2. Conceptual Architecture
Sekcje z nagłówków SKILL.md, w oryginale · 117 linii, 802 słów
Podgląd SKILL.md
---
name: a2a-error-handling
description: Implement A2A error handling — JSON-RPC errors, A2A-specific error codes, task failure states, retry strategies, and graceful degradation. Use when building robust error handling in A2A agents.
allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch
---

# A2A Error Handling

## Before writing code

**Fetch live docs**:
1. Fetch `https://a2a-protocol.org/latest/specification/` for the error handling section
2. Web-search `site:github.com a2aproject A2A error codes` for error code definitions
3. Web-search `site:github.com a2aproject a2a-samples error` for error handling examples
4. Fetch SDK docs for error classes and exception types

## Conceptual Architecture

### Error Categories

A2A has three categories of errors:

1. **JSON-RPC Protocol Errors** — Malformed requests, invalid methods, parse failures
2. **A2A-Specific Errors** — Protocol-level issues specific to A2A operations
3. **Task-Level Failures** — The task itself fails during processing (task state → `failed`)

### JSON-RPC 2.0 Error Format

All errors follow the JSON-RPC 2.0 error response format:
```json
{
  "jsonrpc": "2.0",
  "id": "request-id",
  "error": {
    "code": -32600,
    "message": "Invalid Request",
    "data": { "details": "..." }
  }
}
```

### Standard JSON-RPC Error Codes

| Code | Name | Meaning |
|------|------|---------|
| `-32700` | Parse error | Invalid JSON |
| `-32600` | Invalid request | Not a valid JSON-RPC request |
| `-32601` | Method not found | Method doesn't exist or isn't supported |
| `-32602` | Invalid params | Method parameters are invalid |
| `-32603` | Internal error | Server internal error |

### A2A-Specific Error Codes

| Code | Name | Meaning |
|------|------|---------|
| `-32001` | TaskNotFoundError | The referenced `taskId` doesn't exist |
| `-32002` | TaskNotCancelableError | Task is in a state that can't be canceled (terminal state) |
| `-32003` | PushNotificationNotSupportedError | Agent doesn't support push notifications |
| `-32004` | UnsupportedOperationError | The requested operation is not supported |
| `-32005` | ContentTypeNotSupportedError | Client's accepted output modes don't match agent's capabilities |
| `-32006` | InvalidAgentResponseError | The agent returned an invalid or malformed response |
| `-32007` | ExtendedAgentCardNotConfiguredError | Extended Agent Card is not configured |
| `-32008` | ExtensionSupportRequiredError | A required extension is not supported |
| `-32009` | VersionNotSupportedError | The requested protocol version is not supported |

### Task Failure vs Protocol Error

Important distinction:
- **Protocol errors** return a JSON-RPC error response — the request itself was invalid or couldn't be processed
- **Task failures** return a normal response with the task in `failed` state — the request was valid but the task's processing failed

Example: If a client sends `message/send` with invalid JSON → `-32700` (protocol error). If a client sends a valid message but the agent's LLM call fails → task state becomes `failed` with an error message.

### Server-Side Error Handling

The server should:
1. **Validate JSON-RPC structure** — Return `-32600/-32700` for malformed requests
2. **Validate method** — Return `-32601` for unsupported methods
3. **Validate parameters** — Return `-32602` for invalid params
4. **Check task existence** — Return `-32001` for unknown task IDs
5. **Check capabilities** — Return `-32003/-32005` for unsupported features
6. **Handle extended card** — Return `-32007` if extended Agent Card is not configured
7. **Handle internal errors** — Return `-32603` for unexpected server errors
8. **Set task state** — Transition to `failed` for task-level processing errors

### Client-Side Error Handling

The client should:
1. **Parse the response** — Check for `error` field vs `result` field
2. **Handle by error code** — Different codes need different responses
3. **Retry transient errors** — `-32603` (internal error) may be retryable
4. **Don't retry permanent errors** — `-32601` (method not found) won't succeed on retry
5. **Handle task failures** — Check task state for `failed` and read the error message
6. **Fallback** — Try alternative agents if one fails

### Retry Strategy

| Error Code | Retryable? | Strategy |
|-----------|------------|----------|
| `-32700` | No | Fix the request |
| `-32600` | No | Fix the request |
| `-32601` | No | Method not available on this agent |
| `-32602` | No | Fix the parameters |
| `-32603` | Yes | Exponential backoff, max 3 retries |
| `-32001` | No | Task doesn't exist |
| `-32002` | No | Task can't be canceled |
| `-32005` | No | Content type mismatch |
| `-32007` | No | Extended Agent Card not configured |

### Best Practices

- Always include meaningful error messages, not just codes
- Use the `data` field in JSON-RPC errors for additional debugging context
- Log errors with request IDs and task IDs for traceability
- Implement circuit breakers for agents that are consistently failing
- Set task state to `failed` with a descriptive message when processing fails
- Don't expose internal implementation details in error messages to external clients
- Implement graceful degradation — if one agent in a pipeline fails, handle it upstream
- Test error paths explicitly — they're as important as the happy path

Fetch the specification for the complete list of error codes, their semantics, and any error handling requirements before implementing.

Wersje

W bazie nie ma innych skilli o nazwie a2a-error-handling.

Migawka bazy z 13.11.2026 · wersja paczki d346c5a9a461 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 1 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100error-handling
    Pomaga projektować stany błędów w SaaS: walidację, błędy uprawnień 403, wygasanie sesji, tryb offline, konflikty edycji, limity zapytań i odzyskiwanie po błędach 500.
  • 100error-contract
    Ujednolica obsługę błędów między frontendem a backendem: struktura odpowiedzi, kody statusu i spójna obsługa błędów.
  • 100handling-api-errors
    Wdraża ustandaryzowaną obsługę błędów API z właściwymi kodami statusu HTTP i odpowiedziami błędów.
  • 100handling-api-errors
    Wdraża ustandaryzowaną obsługę błędów API z właściwymi kodami statusu HTTP i odpowiedziami błędów.
  • 80Global Error Handling
    Wdraża obsługę błędów: czytelne komunikaty dla użytkownika, konkretne typy wyjątków, centralne error boundaries i łagodną degradację przy awariach API oraz sieci.
  • 100rs-domain-error
    Projektuje obsługę błędów domeny w Rust: kategorie błędów, strategie odzyskiwania, ponawianie z backoffem, błędy przejściowe i trwałe oraz degradację.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.