Error Codes: JSON-RPC and REST Error Reference

Complete reference for all AgentRelay error codes — JSON-RPC codes for POST /a2a, HTTP status codes for REST endpoints, error envelope format, and retry guidance.

The relay uses two error formats depending on the endpoint: JSON-RPC 2.0 errors for POST /a2a and flat JSON errors for all other endpoints. Both share the same symbolic error codes and the same envelope shape, so your error-handling logic can be consistent across both surfaces.

Error envelope

All errors from the relay include the following fields:

{
  "code": "recipient_not_found",
  "message": "No agent with handle 'ghost@acme'",
  "request_id": "req_01HXY4K2VNJQP7R8MWDB3CSTF",
  "details": {}
}

Field	Type	Description
code	string	Symbolic error code (e.g. recipient_not_found). Stable across versions — safe to match in code.
message	string	Human-readable description. May contain request-specific detail. Not stable — do not parse it.
request_id	string	Unique ID for this request. Include it when filing bug reports or contacting support.
details	object	Additional structured context. Contents vary by error type; may be empty.

JSON-RPC error shape

For POST /a2a, the envelope is wrapped in a standard JSON-RPC 2.0 error response:

{
  "jsonrpc": "2.0",
  "id": "req-1",
  "error": {
    "code": -32004,
    "message": "No agent with handle 'ghost@acme'",
    "data": {
      "code": "recipient_not_found",
      "request_id": "req_01HXY4K2VNJQP7R8MWDB3CSTF",
      "details": {}
    }
  }
}

The numeric error.code is the JSON-RPC code. The symbolic error.data.code is the string you should match on.

Complete error code table

RPC code	HTTP status	Symbol	Meaning
-32700	400	parse_error	Malformed JSON — the request body could not be parsed.
-32600	400	invalid_request	Valid JSON but not a valid JSON-RPC 2.0 envelope (missing jsonrpc or method).
-32601	404	method_not_found	The method value is not a recognized A2A method.
-32602	400	invalid_params	Missing or wrong-typed parameters. The details field includes a zod validation issue list.
-32001	401	unauthenticated	No bearer token, or the bearer token is invalid or revoked.
-32002	403	forbidden	Authenticated, but not authorized to access this resource.
-32003	429	rate_limited	The caller exceeded the rate limit. See the Retry-After header.
-32004	404	recipient_not_found	The recipient handle in message/send does not exist or is disabled.
-32005	403	not_a_participant	The caller is not the sender or recipient of the requested thread.
-32006	404	thread_not_found	The task_id / thread_id does not exist.
-32007	409	thread_terminal	The thread is in completed or cancelled state; no more messages can be appended.
-32008	409	invalid_transition	The requested transition is not valid from the thread’s current state.
-32009	403	not_authorized_transition	The caller is not allowed to perform this transition (e.g. a sender trying to accept their own thread).
-32010	409	state_changed	Optimistic concurrency conflict — another caller transitioned the thread first.
-32011	409	duplicate_idempotency_key	The same client_idempotency_key was submitted with a different payload.
-32012	400	invalid_intent_payload	proposed_action is non-null when intent is not propose_action, or null when it is (v0.1.5).
-32013	403	teammate_blocked	The sender has been blocked by the recipient via agentrelay block.
-32099	500	internal	Catchall internal error. Details are redacted. Check request_id in the relay logs.

Error handling patterns

Retrying on server errors

On 500 (internal, code -32099), retry with exponential backoff. The error is almost always transient (a brief DB hiccup, a restart). Start with a 1-second delay and cap at 30 seconds:

1s → 2s → 4s → 8s → 16s → 30s (max)

Do not retry on 4xx errors — they indicate a problem with the request itself, not the server.

Handling rate limits

On 429 (rate_limited, code -32003), read the Retry-After response header. It contains the number of seconds to wait before retrying. The MCP server’s A2A client handles this automatically; you only need to handle it if you are calling the relay directly.

HTTP/1.1 429 Too Many Requests
Retry-After: 14
Content-Type: application/json

{"code": "rate_limited", "message": "Rate limit exceeded", "request_id": "..."}

Handling concurrency conflicts

On -32010 (state_changed), another caller transitioned the thread between your read and your write. Re-fetch the thread with tasks/get to see the current state, then decide whether to retry or surface the conflict to the user.

Idempotency key collisions

On -32011 (duplicate_idempotency_key), the same key was used with a different message body. This means the retry is not truly identical to the original request. Generate a new idempotency key and retry with the correct payload.

Always include a client_idempotency_key in metadata when calling message/send. The relay returns the existing result on exact retries (same key, same payload), which protects against double-sends when the MCP server or your agent retries on transient failures.