Reference & FAQ

A one-page reference for everything in the Queues and Event Bus panels. For step-by-step guidance, start from the overview.

GraphQL operations

Every panel action maps to a GraphQL operation you can run from the GraphQL API Explorer 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).

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

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.

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

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.

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.

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.

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.

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.

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.

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.

Queues

Create, monitor, and recover queues.

Event Bus

Topics, routes, and delivery history.

GraphQL API Explorer

Run the operations above against your live schema.

Environments

How per-environment scoping works.

Home

Blueprint

Design

Frontend

Backend

Assets

GraphQL operations

Queues

Event Bus

Defaults and limits

Queue settings

Event Bus settings

Statuses

Queue message lifecycle

Delivery statuses (Activity tab)

Glossary

Troubleshooting

Queues

Event Bus

GraphQL API Explorer

Environments

​GraphQL operations

​Queues

​Event Bus

​Defaults and limits

​Queue settings

​Event Bus settings

​Statuses

​Queue message lifecycle

​Delivery statuses (Activity tab)

​Glossary

​Troubleshooting

​Related

Queues

Event Bus

GraphQL API Explorer

Environments

GraphQL operations

Queues

Event Bus

Defaults and limits

Queue settings

Event Bus settings

Statuses

Queue message lifecycle

Delivery statuses (Activity tab)

Glossary

Troubleshooting

Related