Errors - Relay

Errors use one JSON envelope:

{ "error": { "code": "invalid_request", "message": "link parts require a public HTTPS url" } }

Branch on code and log message. Handle unknown codes by HTTP status class.

Error codes

Code	Status	Meaning
`unauthorized`	401	Missing, malformed, or revoked token. Update the credential before retrying.
`forbidden`	403	The agent is not a participant or its installation ended.
`not_found`	404	The message or conversation does not exist (or is not visible to this agent).
`invalid_request`	422	Validation failure. The `message` names the rule: part shape, size, or missing field. A stream that ends before `finish`, aborts, or errors lands here too.
`malformed_stream`	400	A streamed reply broke UIMessageStream v1 framing. Fix the producer; retrying the same bytes fails again.
`request_timeout`	408	A streamed reply stalled past the 30-second idle or 10-minute total ceiling. Nothing was committed. Retry the whole stream.
`payload_too_large`	413	A streamed reply or an attachment upload exceeded its byte ceiling. See Limits.
`idempotency_conflict`	409	The client-minted `message_id` was reused with a different request body or sender. Reusing it for the same send returns the original message.
`conflict`	409	A webhook URL is already registered. Use the existing subscription or choose another URL.
`limit_exceeded`	409	The agent already has five enabled webhook endpoints. Disable or delete one before enabling another.
`rate_limited`	429	A ceiling was reached: too many messages in this conversation, or a spent write budget on reactions, receipts, typing, or attachment uploads. Wait for the `Retry-After` header, then retry the same send with the same `message_id`.
`server_configuration_error`	503	Relay cannot perform this operation because required server-side delivery configuration is unavailable. Retry later.
`internal_error`	500	Relay-side failure. Safe to retry with backoff; your idempotency key prevents duplicates.

Retry guidance

Outbound calls to Relay:

Response	What to do
Network error, timeout, `429`, `5xx`	Retry with exponential backoff and jitter, capped around 60 s. Reuse the same `message_id` on every send attempt
Any other `4xx`	Update the request or the credential before trying again

Inbound webhook deliveries from Relay:

Return 408, 429, or a 5xx when you want Relay to retry.
Any other non-2xx dead-letters the delivery immediately.
Deduplicate every attempt by event_id.

See also