> ## 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

The panel calls these connections **routes**; the API still names the operations after the older term, **subscription**.

| 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 (the panel's "New event" button). |
| `deleteTopic` | Mutation | Delete a topic. |
| `subscriptions` | Query | List a topic's routes. |
| `createSubscription` | Mutation | Add a route (filter + target: queue, REST, or GraphQL). |
| `deleteSubscription` | Mutation | Remove a route. |
| `setSubscriptionActive` | Mutation | Pause or resume an endpoint route. |
| `publishEvent` | Mutation | Publish an event (event type + JSON body, optional dedup key) to a topic. |
| `topicDeliveries` | Query | Delivery history for a topic's endpoint routes (powers the **Activity** tab). |

<Note>
  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.
</Note>

## 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 |
| - | - |
| Target types | **Queue** (one of your queues), **REST** (external endpoint only, for now), **GraphQL** (your own project's API by default, or an external endpoint). |
| Filter modes | All (`>`), an exact event type, or a single-segment wildcard pattern (`*`). |
| Description | Topics take an optional description. |
| GraphQL → My archie-core API | Search-select an existing mutation from your schema instead of writing one. Still requires a **Token / API key**, sent as `Authorization` — internal delivery is not secret-free. |
| REST → My archie-core API | Not available yet; shown as disabled in the target picker. |
| External targets (REST or GraphQL) | HTTPS required; blocked for private/loopback/metadata hosts (SSRF safeguard); credentials and custom headers encrypted at rest; one-time HMAC signing secret shown on save. |
| HTTP method | REST targets expose a method dropdown (`POST` default). GraphQL targets always `POST` the mutation. |
| 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. |
| Delivery attempts | 1–20, set **per route** for REST/GraphQL targets. Exhausted deliveries move to that route's own dead-letter queue. Queue targets use the destination queue's own settings instead. |
| Endpoint retries | Automatic, with increasing back-off, up to the route's delivery attempts. |

<Note>
  Per-tenant quotas (how many queues, topics, and routes 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.
</Note>

## 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 route's own 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 routes. |
| Route (panel) / Subscription (API) | SNS subscription | A rule that delivers matching events from a topic to a target. The UI calls it a route; `createSubscription` and related GraphQL operations still use the older name. |
| 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

<AccordionGroup>
  <Accordion title="I created a queue/topic but don't see it">
    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.
  </Accordion>

  <Accordion title="My worker processes messages twice">
    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.
  </Accordion>

  <Accordion title="Messages are retried while my worker is still running">
    The job exceeds the queue's **Processing time**. Increase it on the queue's **Settings** tab, or extend it from the worker while it runs.
  </Accordion>

  <Accordion title="A route keeps failing">
    Open the topic's **Activity** tab and read the status codes for that route (queue-target routes show their health on the queue itself, not here). Fix the cause (auth for `4xx`, availability for `5xx`) — the route retries automatically up to its configured delivery attempts, then parks the event in its own dead-letter queue.
  </Accordion>

  <Accordion title="I published an event but a route didn't receive it">
    Check the route's **filter** on the topic's Routes tab — the event type may not match "An exact type" or the Pattern prefix. Also confirm the route is **Active**.
  </Accordion>

  <Accordion title="My external endpoint rejects the delivery">
    Verify you're checking the **HMAC signature** with the secret shown at creation time, and that any **token or custom headers** you configured are what your endpoint expects. External URLs must be HTTPS and publicly reachable.
  </Accordion>

  <Accordion title="I lost the external signing secret">
    The secret is shown only once. Recreate the route to generate a new one, and update your endpoint to verify against it.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Queues" icon="layer-group" href="/docs/features/backend/app-services/queues-and-event-bus/queues">
    Create, monitor, and recover queues.
  </Card>

  <Card title="Event Bus" icon="tower-broadcast" href="/docs/features/backend/app-services/queues-and-event-bus/event-bus">
    Topics, routes, and delivery history.
  </Card>

  <Card title="GraphQL API Explorer" icon="code" href="/docs/features/backend/graphql-api-explorer/overview">
    Run the operations above against your live schema.
  </Card>

  <Card title="Environments" icon="code-branch" href="/docs/features/backend/environments/overview">
    How per-environment scoping works.
  </Card>
</CardGroup>