Troubleshooting

Credentials

Symptom	Cause	Fix
The token request answers invalid_client	Wrong client id or secret, a previous secret after its overlap, a revoked connection, or credentials for the other environment	Check the token URL matches the environment; check the connection on Apps and credentials; rotate if the secret is lost
401 producer.unauthenticated with a fresh token	Sent to the other environment's API, or the header isn't Authorization: Bearer <token>	Match the environments; check the header
401 after working fine	The token expired, or the secret was rotated: every earlier token stops within about 30 seconds	Get a new token; refresh before expires_in runs out
403 producer.not_registered	The connection was revoked, an identity-provider client isn't bound, or an AWS role isn't registered for this workspace	Check Sign-in methods on the connection; connect the app again if it was revoked
403 principal.not_verified	Your AWS role is registered but hasn't run the verify command	Run the command the portal shows, signed with the role; press New challenge if it expired
403 tenant.mismatch	{t} in the URL isn't your connection's workspace	Use the tenant claim of your token
429 rate.limited or quota.exceeded	Too many requests, or a token fetched per message. Requests signed with an AWS role share one limit with every other AWS signer	Reuse tokens for their hour; back off, honouring Retry-After. See Limits
403 request.blocked	The bus's firewall refused the request	Check what your client sends; ask RND if it's a normal message
403 {"message":"…"} on a signed route	The request is unsigned, badly signed or signed with expired AWS credentials, or your own policy doesn't let the role call the API	Check the signing and your AWS credentials; allow Invoke on the bus API
403 {"message":"Missing Authentication Token"}	A path the API doesn't have: check /v1/ and the route	Check the URL

An app RND manages in the bus configuration gets its tokens from the token URL RND sent it, with scope sombus/publish; invalid_scope there means the scope is missing or misspelt.

Messages refused

Symptom	Cause	Fix
400 envelope.format.uuid though your ids look like UUIDs	Braces, a prefix, or a custom id format	The plain form: 0199a1c4-7a2e-7b31-8c55-4d2f9e6a1b07
400 envelope.format.date-time	No time zone, a space instead of T, or a local format	2026-09-24T14:00:00Z
400 envelope.enum at /originating_system/system_type	Your tool's own type (playout, cms, mam…)	A SOM value; custom if nothing fits
400 envelope.additionalProperties at /extensions	Extension keys not under com.<vendor>.	"com.acme.rundown_slot": 3
Many envelope.required and envelope.additionalProperties errors at once	You sent a bare payload, not an envelope	Wrap the payload in an envelope
Passes your validator, refused by the bus	Format assertion off, another schema version, or the payload checked against the wrong schema	See Validate in your own tests
409 sequence_number.not_increasing on your first message	That story_id already exists in your workspace, from an earlier run	A new story_id per run, with your prefix
409 sequence_number.not_increasing in the middle of a story	Two writers, parallel sends for one story, or your product lost its counter	One writer; wait for each answer; store the sequence with the story
409 snapshot.members_missing	Your product sends only what changed	Send the whole story every time
409 message_id.reused on a retry	Your retry rebuilt the message (a new timestamp) and kept the id	Keep and resend the exact original
413 message.too_large	Media, transcripts or long text in the message	References only

Every rule id: the rule catalogue.

Consuming

Symptom	Cause	Fix
503 consumer.queue_unavailable	The connection's queue is still being set up	Wait until Consumer connections shows Ready; retry after Retry-After
403 producer.not_registered on the pull API	A producer's token, or a revoked or removed consumer connection	Use the consumer connection's own credentials; restore it if it was revoked
403 consumer.not_owner	{c} in the URL isn't your connection	Use your client id as {c}
AccessDenied from SQS	Your reader role is still Awaiting proof, was verified less than a few minutes ago, or your role's own policy lacks the SQS actions; or you called GetQueueUrl, which a reader role isn't granted	Run the verify command, wait for Verified, allow the four actions on both queue ARNs, and use the queue URL from the portal; see Consumer connections
Nothing arrives	No matching message types, topic prefix or source; the message was refused at the gateway; or it was published before the connection was ready	Check the message on the portal's timeline; check the connection's filter, including its source
Other apps' messages arrive	Your connection receives every matching message in the workspace, from every app in it	Narrow the message types, use a topic prefix, or filter on your own correlation_ids
One story stops, the others flow	A message of that story keeps failing in your handler	Fix the handler. At the attempt limit it moves to your dead-letter queue
The same message twice	At-least-once delivery, a replay or a redrive	Be idempotent on message_id
An old snapshot after a newer one	A redrive or a replay	Keep the highest sequence_number per story

Portal

Symptom	Cause	Fix
Your story isn't on the Story timeline	You're looking at another workspace; nothing was accepted for it yet; it's older than 7 days; or the app is one RND manages in the bus configuration	Check the Workspace menu and Activity; for an app RND manages, ask RND
A refusal isn't on the story's timeline	The bus couldn't read a story id from it (not JSON, or the envelope failed)	Look in Activity
The Playground accepts a message that publishing refuses with 403	The Playground doesn't check your app's grants	Dry-run on your workspace's validate route, or compare with the connection's grants
No invitation shows when you sign in	It expired after 14 days, or was sent to another address	Ask RND for a new one
Sign-in asks for a code you don't have	Multi-factor sign-in is required, and your authenticator is on another device	Ask your RND contact to reset it: you can't use Ask RND until you're signed in

Still stuck

Ask RND, with the environment, the time window, message_ids and rule ids. Never secrets or real content.