# Error & Reason Codes (/connectors/rabbitmq/reference/error-codes)



The RabbitMQ (AMQP 0-9-1) connector returns standard AMQP 0-9-1 channel/connection close codes.
This reference lists every code the connector emits, what triggers it, and whether it closes the
offending channel or the whole connection. All codes are verified in the connector source.

## Reason code table [#reason-code-table]

| Code  | Constant                  | Meaning             | Trigger                                                                                                                    |
| ----- | ------------------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `311` | `replyContentTooLarge`    | content-too-large   | body > `MaxBodySize`                                                                                                       |
| `312` | `replyNoRoute`            | no-route            | `mandatory=true` unroutable → `basic.return`                                                                               |
| `313` | `replyNoConsumers`        | no-consumers        | **reserved** — defined but not currently emitted in non-test source                                                        |
| `320` | `replyConnectionForced`   | connection-forced   | shutdown / conn-limit / graceful close                                                                                     |
| `402` | `replyInvalidPath`        | invalid-path        | bad / reserved vhost (incl. literal `default`)                                                                             |
| `403` | `replyAccessRefused`      | access-refused      | auth fail / Read deny on consume / `amq.*` client declare / delete pre-declared / exclusive-consumer conflict              |
| `404` | `replyNotFound`           | not-found           | passive declare of a missing exchange/queue                                                                                |
| `405` | `replyResourceLocked`     | resource-locked     | exclusive-queue cross-connection access                                                                                    |
| `406` | `replyPreconditionFailed` | precondition-failed | redeclare mismatch, `user-id` mismatch, bad `expiration`, unknown delivery tag, reply-to no-ack rule, channel-length > 255 |
| `501` | `replyFrameError`         | frame-error         | bad frame-end, oversized frame                                                                                             |
| `502` | `replySyntaxError`        | syntax-error        | malformed method / field-table                                                                                             |
| `503` | `replyCommandInvalid`     | command-invalid     | unknown exchange type, out-of-state method, unsupported SASL mechanism (non-PLAIN)                                         |
| `504` | `replyChannelError`       | channel-error       | data-plane / array failure                                                                                                 |
| `505` | `replyUnexpectedFrame`    | unexpected-frame    | wire-level sequencing error                                                                                                |
| `530` | `replyNotAllowed`         | not-allowed         | duplicate consumer tag on a channel (RabbitMQ-dialect connection error)                                                    |
| `540` | `replyNotImplemented`     | not-implemented     | `tx.*`, `exchange.bind/unbind`, `immediate=true`, `basic.recover-async`, `connection.update-secret`                        |
| `541` | `replyInternalError`      | internal-error      | broker not ready (gated; new ops rejected until ready)                                                                     |

<Callout type="info">
  **`313 replyNoConsumers` is reserved.** It is defined in the connector source but is not
  currently emitted by non-test code. It is listed here for completeness only.
</Callout>

## Channel vs connection errors [#channel-vs-connection-errors]

The scope of a close code tells you what gets torn down:

* **Channel errors** (e.g. `404`, `405`, `406`, `504`) close the offending channel; the
  connection survives.
* **Connection errors** (e.g. `320`, `403` auth, `501`, `502`, `503`, `505`, `530`) close the
  whole connection.

## Common triggers by scenario [#common-triggers-by-scenario]

| Scenario                                                                   | Code                         |
| -------------------------------------------------------------------------- | ---------------------------- |
| Publish to a direct exchange with an unmatched key (no `mandatory`)        | silent drop (no code)        |
| `basic.publish(mandatory=true)` unroutable                                 | `312`                        |
| `expiration` not `^\d+$`                                                   | `406`                        |
| Consume `amq.rabbitmq.reply-to` with `no-ack=false`                        | `406`                        |
| `user-id` ≠ `Claims.ClientID` (auth on)                                    | `406`                        |
| Read deny on consume                                                       | `403`                        |
| Bad / reserved (`default`) vhost; illegal vhost charset                    | `402`                        |
| Exclusive-queue cross-connection access                                    | `405`                        |
| Redeclare with mismatched args; unknown delivery tag; channel name > 255   | `406`                        |
| Passive declare of a missing exchange/queue                                | `404`                        |
| Client declares an `amq.*` exchange / deletes a pre-declared exchange      | `403`                        |
| Body > `MaxBodySize`                                                       | `311` / `406`                |
| Bad frame-end / oversized frame / malformed method                         | `501` / `502`                |
| Unsupported SASL mechanism (non-PLAIN)                                     | `503`                        |
| `tx.*` / `exchange.bind/unbind` / `immediate=true` / `basic.recover-async` | `540`                        |
| Connection limit reached                                                   | `320`                        |
| Broker not ready (gated)                                                   | `541`                        |
| Auth failure (bad JWT)                                                     | `403` + `auth.failure` audit |

## Related [#related]

<Cards>
  <Card title="Capabilities" href="/connectors/rabbitmq/reference/capabilities" description="Supported methods, the not-implemented (540) set, inert arguments, and the nine gotchas." />

  <Card title="Channel Mapping" href="/connectors/rabbitmq/reference/channel-mapping" description="The name charset and reserved-vhost rules behind the 402 / 406 codes." />

  <Card title="Reliability" href="/connectors/rabbitmq/how-to/reliability" description="Handling 312 returns, DLX, and the publisher-confirm deviations in client code." />

  <Card title="Authentication" href="/connectors/rabbitmq/how-to/authentication" description="The 403 / 406 / 503 codes behind SASL PLAIN and per-channel authorization." />
</Cards>