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

# Errors

> Error format and status code guidance.

Error response shape:

```json theme={null}
{
  "error": "message"
}
```

Common status codes:

* `400` invalid request
* `401` missing/invalid bearer token
* `403` missing scope
* `404` resource not found
* `409` idempotency conflict
* `422` plan/validation limits
* `429` rate limited
* `500` provider/internal failure

Use idempotency keys and exponential backoff for retryable failures.

## Inbound webhook statuses

When Mailgun forwards inbound mail to `/webhooks/mailgun/inbound`:

* `200` with `{"ok": true}`: inbound accepted and saved.
* `200` with `{"ok": true, "duplicate": true}`: duplicate delivery ignored.
* `202` with `{"ok": true, "ignored": true}`: recipient inbox not found.
* `401`: signature verification failed (`MAILGUN_WEBHOOK_SIGNING_KEY` mismatch).