Troubleshooting publishing connections

Most connection problems fall into a handful of patterns. Each section below starts with what you see in Serpio, names the usual cause, and gives the fix. The same entries appear inside each connection's own guide under Troubleshooting, next to the setup steps.

The authorization popup does not open, or Serpio keeps waiting

This applies to Blogger and to WordPress.com, which authorize through a popup window. There are two symptoms.

• The dialog shows "Your browser blocked the authorization popup. Allow popups for Serpio and try again." The browser stopped the window before it opened.
• You finished authorizing in the popup, but the Serpio button still reads "Waiting for authorization…".

1. 1

   Allow popups for Serpio

   Use the browser's address-bar icon or its site settings, then click the connect button again. Serpio opens the window during your click, so a popup blocker or strict privacy extension is the usual culprit.

2. 2

   Return to the Serpio window and let the check finish

   Serpio polls for the new connection after the platform redirects. The provider window may stay open; that is fine.

3. 3

   If authorization expired, start again from Serpio

   Complete one authorization window at a time. Two open windows confuse the check.

4. 4

   Check whether the connection saved before retrying

   Refresh Connections. A card reading Connected or Finish setup means it worked and only the confirmation was lost.

The credentials are not accepted

For API-key connections, Test & save verifies the credentials before anything is stored. A rejection means the platform said no. What "no" means differs per platform.

1. 1

   Paste the complete value

   Application Passwords contain spaces; that is fine. Ghost keys contain a colon; keep it.

2. 2

   Use credentials for the same site or account you entered in Serpio

   A key from a staging site will not work against the production URL.

3. 3

   If the key was revoked, create a replacement in the platform

   Serpio encrypts secrets at rest and never displays them again, so you cannot copy the old one back out.

4. 4

   Read the message under the form

   A message starting with Unauthorized points at the credential itself. Forbidden points at the account's permissions on the platform.

The site or blog is missing, or the test fails

Blogger and WordPress.com show a Destination block after connecting. If your blog or site is not in the list, or Test connection fails, the cause is usually on the account side.

1. 1

   Confirm the destination exists in the account you connected

   Serpio lists only blogs and sites where that account can create posts. Read-only ones appear disabled in the dropdown.

2. 2

   Reopen the connection to reload the choices

   Click Manage on the connection card, then Customize destination.

3. 3

   Run Test connection and read the message

   "Credentials and destination are reachable." is a full pass. "Credentials work; choose a destination to finish setup." means the credentials are fine but no destination is saved. Pick one and click Save connection.

4. 4

   If the test fails, check permissions and the saved destination first

   A transient failure keeps the connection manageable, so you can test again once the platform is back. The provider page records the outcome under Last checked.

The card says Reconnect, or Connection needs attention

These are two different states with two different fixes.

Reconnect

The platform rejected the saved credentials or token. Common after revoking an Application Password, rotating a Ghost integration, removing Serpio from your Google account, or a failed token refresh. The dialog reads "Reconnect required." followed by the last error. Nothing is sent until you reconnect.

Connection needs attention

A transient error, such as the platform being unreachable during a test or a delivery. The dialog reads "Connection needs attention." followed by the last error, and the provider page shows a Connection needs attention strip with the same message. Credentials are still saved.

1. 1

   For Reconnect on an API-key connection, click Manage, then Reconnect credentials

   Enter the replacement credentials and click Test & reconnect. Changed your mind? Keep saved credentials puts the form back without touching anything.

2. 2

   For Reconnect on Blogger or WordPress.com, click Reconnect

   The button on the provider page reopens the authorization popup. Approve access again with the same account.

3. 3

   For Connection needs attention, read the error and run Test connection

   Do this when the platform is available again. The card returns to Connected on a passing test.

4. 4

   Use Disconnect only to start over

   It clears the saved destination, mappings, and publishing settings. Serpio asks first, with the warning "Future drafts won't auto-publish here until you reconnect." Reconnecting credentials keeps all of those.

I cannot find the article after sending it

1. 1

   Check the result in Serpio first

   Open the article and read Publishing history. Draft saved means the post is unpublished on the platform. Live means it is public. Check destination means Serpio does not know.

2. 2

   Look in the right place

   Drafts are hidden from public listings. WordPress and Ghost list them under Posts with a Drafts filter, Blogger under Posts with the Draft filter, DEV in the dashboard as unpublished. The Open draft link takes you straight there when the platform returned one.

3. 3

   For Check destination, search before retrying

   Look for the title in drafts and in published posts. Retry only after you have confirmed the article is absent, and tick "I checked the destination and confirmed this article was not created." The full flow is in Publishing history and retries.

4. 4

   Treat a webhook Created result as an acknowledgement, not a post

   It means your receiver accepted the payload. Whether it created an article anywhere is up to the receiver.

The webhook endpoint rejects the request, or nothing appeared

A webhook connection is only as good as the receiver. Serpio sends a signed JSON POST and expects a 2xx response within 10 seconds.

• Rejected on Test & save: the receiver did not return 2xx for the connection.test event. Check that the URL is public HTTPS. Production rejects plain HTTP with "Production webhooks must use HTTPS." and private or loopback hosts with "Webhook host resolves to a private or unsafe network address." Redirects are not followed.
• Signature failures: compute HMAC-SHA256 over the timestamp, a dot, and the raw request body, using the same secret you entered in Serpio, and compare it with X-Serpio-Signature (prefixed sha256=). Read the raw body before any JSON middleware reformats it.
• Response too large or too slow: Serpio reads at most 64 KB of the response and gives up after 10 seconds. Respond quickly with a small body and do the heavy work afterwards.
• Rate limited: a 429 response is retried automatically. A 5xx or a timeout becomes Check destination, so make your receiver idempotent on X-Serpio-Delivery.
• Nothing appeared downstream: a 2xx only tells Serpio the receiver accepted the payload. Check the receiver's logs for the delivery ID, and process each ID once.

The card shows Upgrade

Native connections are part of paid plans. On Free, saved connections show an Upgrade pill, the publish dialog labels them Upgrade needed, and publishing stops with "Native publishing connections are available on every paid Serpio plan. Manual exports remain available on Free." Nothing about the connection is lost; upgrading restores it as saved. In the meantime Export and the platform guides work on every plan. See Plans and credits.