> ## Documentation Index
> Fetch the complete documentation index at: https://archie.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Reference & FAQ
> A quick reference for Queues and the Event Bus: the GraphQL operations, default settings and limits, message and delivery statuses, a glossary that maps plain-language terms to their technical names, and troubleshooting.
A one-page reference for everything in the Queues and Event Bus panels. For step-by-step guidance, start from the [overview](/docs/features/backend/app-services/queues-and-event-bus/overview).
## GraphQL operations
Every panel action maps to a GraphQL operation you can run from the [GraphQL API Explorer](/docs/features/backend/graphql-api-explorer/overview) or your app. The exact fields and arguments are documented live in the Explorer's schema; the tables below list what each operation is for.
### Queues
| Operation | Type | What it does |
| ----------------- | -------- | ------------------------------------------------------------------------------------ |
| `queues` | Query | List the queues in the current environment. |
| `queueStats` | Query | Live counts for one queue: pending, in-process, oldest-message age, error-list size. |
| `createQueue` | Mutation | Create a queue (name, plus optional processing time, max attempts, retention). |
| `updateQueue` | Mutation | Change a queue's mutable settings. |
| `deleteQueue` | Mutation | Delete a queue. |
| `sendMessage` | Mutation | Put a message on a queue (with an optional dedup key). |
| `receiveMessages` | Mutation | Pull a batch of messages for a worker (supports long polling). |
| `deleteMessage` | Mutation | Confirm a processed message using its receipt handle. |
| `redrive` | Mutation | Move a queue's error list (dead-letter queue) back to the main queue. |
### Event Bus
| Operation | Type | What it does |
| ----------------------- | -------- | ------------------------------------------------------------------------------------ |
| `topics` | Query | List topics in the current environment. |
| `topicStats` | Query | Event volume, bytes, and retention for a topic. |
| `createTopic` | Mutation | Create a topic. |
| `deleteTopic` | Mutation | Delete a topic. |
| `subscriptions` | Query | List a topic's subscriptions. |
| `createSubscription` | Mutation | Add a subscription (filter + target: queue, your API, or external endpoint). |
| `deleteSubscription` | Mutation | Remove a subscription. |
| `setSubscriptionActive` | Mutation | Pause or resume an endpoint subscription. |
| `publishEvent` | Mutation | Publish an event (event type + JSON payload) to a topic. |
| `topicDeliveries` | Query | Delivery history for a topic's endpoint subscriptions (powers the **Activity** tab). |
The API is scoped to the current project and environment the same way the panels are. Calls made with an API key follow your [Role-Based Access](/docs/features/backend/app-services/role-based-access) permissions.
## Defaults and limits
### Queue settings
| Setting (panel label) | Default | Maximum | Technical term |
| -------------------------------- | ---------- | -------- | --------------------------- |
| Processing time (s) | 30 seconds | 12 hours | Visibility timeout |
| Attempts before moving to errors | 5 | 20 | Max delivery / max receives |
| Message retention (days) | 4 days | 14 days | Message retention |
| Message size | — | 256 KB | Max message size |
### Event Bus settings
| Setting | Note |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Filter modes | All (`>`), one exact event type, or a single-segment wildcard (`*`). |
| Description | Topics and subscriptions take an optional description. A subscription's description is also delivered with the event (a `subscriptionDescription` field in the body and an `X-Archie-Subscription-Description` header). |
| Internal targets | Your project's GraphQL or REST API — authentication resolved automatically, no secret. |
| External targets | HTTPS required; blocked for private/loopback/metadata hosts (SSRF safeguard); credentials encrypted at rest; one-time HMAC signing secret. |
| HTTP method | `POST` (default), `PUT`, `PATCH`, or `DELETE` per external subscription. |
| Dynamic URL parameters | The external URL may contain `{field}`, `[field]`, or `:field` placeholders, resolved from each event's payload at delivery; SSRF checks run on the final address. |
| Custom headers | Multiple name/value headers sent on every delivery, encrypted at rest; only the names are shown afterward. Platform headers (signature, `Content-Type`, `X-Archie-*`) always win. |
| Endpoint retries | Automatic, with increasing back-off; exhausted deliveries move to the subscription's error list. |
Per-tenant quotas (how many queues, topics, and subscriptions an environment may create) apply and are enforced when you create a resource. If you hit a limit, the panel tells you in plain language.
## Statuses
### Queue message lifecycle
| State | Meaning |
| -------------------- | ----------------------------------------------------------- |
| **Pending** | Waiting to be picked up. |
| **In flight** | Received by a worker and temporarily invisible to others. |
| **Confirmed** | Acknowledged and removed. |
| **Error list (DLQ)** | Failed its maximum attempts and moved aside for inspection. |
### Delivery statuses (Activity tab)
| Status | Meaning |
| ------------------------ | ------------------------------------------------------------------------------------------------------ |
| Green `2xx` | The target accepted the delivery. |
| Red `4xx` | The target rejected it (authentication or validation). Retrying rarely helps until the cause is fixed. |
| Red `5xx` / timeout | The target was unavailable. Retried automatically. |
| `failed` / `dead_letter` | The delivery exhausted its retries and moved to the subscription's error list. |
## Glossary
Product terms in the panels, mapped to their industry names.
| In Archie | Industry term | Meaning |
| ----------------- | ---------------------------- | ------------------------------------------------------------------------ |
| Queue | SQS queue | A point-to-point message buffer consumed by one worker at a time. |
| Event Bus / Topic | SNS topic / EventBridge | A publish/subscribe channel that fans one event out to many subscribers. |
| Subscription | SNS subscription | A rule that delivers matching events from a topic to a target. |
| Processing time | Visibility timeout | How long a worker has to confirm a message before it's retried. |
| Max attempts | Max delivery / receive count | Retries before a message moves to the error list. |
| Error list | Dead-letter queue (DLQ) | Where messages that keep failing are preserved. |
| Redrive | Redrive | Moving the error list back to the main queue to retry. |
| Dedup key | Deduplication ID | Suppresses accidental duplicate sends within a window. |
| In flight | In-flight | A message currently held by a worker. |
| Pending | Queue depth | Messages waiting to be consumed. |
## Troubleshooting
Confirm you're viewing the **same environment** you created it in. Queues and topics are per-environment; switching the environment selector changes the whole list.
Delivery is *at least once*. Make the worker **idempotent** (safe to run twice for the same input) and use a **dedup key** on send to suppress accidental duplicate sends.
The job exceeds the queue's **Processing time**. Increase it on the queue's **Configuration** tab, or extend it from the worker while it runs.
Open the topic's **Activity** tab, filter to **Failed only**, and read the status codes. Fix the cause (auth for `4xx`, availability for `5xx`), then redrive the subscription's error list.
Check the subscription's **filter** — the event type may not match. The wizard's live preview shows exactly which recent event types a filter matches. Also confirm the subscription is **Active**.
Verify you're checking the **HMAC signature** with the secret shown at creation time, and that any **Bearer token or custom headers** you configured are what your endpoint expects. External URLs must be HTTPS and publicly reachable.
The secret is shown only once. Recreate the subscription to generate a new one, and update your endpoint to verify against it.
## Related
Create, monitor, and recover queues.
Topics, subscriptions, and delivery history.
Run the operations above against your live schema.
How per-environment scoping works.