> ## Documentation Index
> Fetch the complete documentation index at: https://docs.relayapp.im/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors & limits

> Error codes, retry behavior, and API limits.

Errors use one JSON envelope:

```json theme={null}
{ "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 guidance

* **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`.

## Limits

Every size, count, and rate ceiling lives in one place:
[Limits and rate limits](/reference/limits).

## See also

* [API overview](/api-reference/overview)
* [Delivery model](/guides/delivery-model)
* [Limits and rate limits](/reference/limits)
* [Authentication](/authentication)