Errors & limits

Errors use one JSON envelope:

{ "error": { "code": "invalid_request", "message": "link_preview 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, missing field, or malformed native stream.
`idempotency_conflict`	409	The `Idempotency-Key` was reused with a different request body. Reusing it with the same body returns the original message instead.
`conflict`	409	The requested webhook URL is already registered. Use the existing endpoint 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	Too many messages in this conversation inside the current window. Wait for the `Retry-After` header (seconds), then retry the same request with the same `Idempotency-Key`.
`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 network errors, timeouts, 429, and 5xx with exponential backoff and jitter, capped around 60 s. Reuse the same Idempotency-Key for each attempt.
For other 4xx responses, update the request or credential before trying again.
For incoming webhooks, 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.

Every size, count, and rate ceiling lives in one place: Limits and rate limits.