Event error codes (mpbx-events)
Codes raised by mpbx_events (W1-PBX-05): the Bus, the event envelope and the transactional
outbox. Kinds map to HTTP statuses in the API layer as for the common codes.
Messages never contain event payloads, row values or secrets. Guide:
docs/guides/domain-events.md.
| Code | Kind | Meaning | What to do |
|---|---|---|---|
MPBX-EVENTS-ENCODE | internal | An event could not be serialized to JSON. | Report it: this is a bug. |
MPBX-EVENTS-DECODE | invalid_argument | JSON is not a valid event envelope (unknown type, missing field). In the outbox relay, the row is moved to the dead letters (dead_at) with this code in last_error. | Usually a newer release wrote the event before a rollback: upgrade again, then replay the dead letters (see the guide). |
MPBX-EVENTS-LAGGED | unavailable | A subscriber of the in-process Bus fell behind and missed events; the message gives the count. Retryable: the subscription continues. | Speed up the consumer or raise the Bus capacity; consumers that need every event resynchronise or use the durable Bus. |
MPBX-EVENTS-CLOSED | unavailable | The Bus was shut down. | Expected during shutdown; otherwise restart the process. |
MPBX-EVENTS-TENANT-MISMATCH | permission_denied | An event was written to the outbox for another tenant than the one the transaction is scoped to (mpbx.tenant_id). Nothing was written. | A bug in the caller: build the event with the transaction's tenant. |
MPBX-EVENTS-SYSTEM-SCOPE-REQUIRED | permission_denied | The outbox relay, pending_count or prune_published ran on a transaction that is not a system-scope one (role mpbx_system). Nothing was read or changed. | A bug in the wiring: build the relay with storage::pg::SystemTx::opener(pool, system_ctx) and run pending_count / prune_published on a SystemTx connection. |
MPBX-EVENTS-OUTBOX-DB | unavailable or internal | A database error in the outbox (the message carries the SQLSTATE only). unavailable (retryable) when Postgres is unreachable; internal otherwise, for example an unknown tenant (23503) or a duplicate event id (23505). | Check Postgres health; for internal, report it with the log line. |