"Unsupported Confluence API call" when deploying updated documents with updated confluencebuilder

[fizyk]

I'm trying to update confluencesphinxbuilder and at the same time publish documentation with new page.

I'm getting a

Unsupported Confluence API call

An unsupported Confluence API call has been made. See the following
details for more information:

REQ: POST
RSP: 500
URL: https://imaginecommunications.atlassian.net/wiki/
API: api/v2/pages/[id]/properties
DATA: {
  "errors": [
    {
      "status": 500,
      "code": "INTERNAL_SERVER_ERROR",
      "title": "Internal Server Error",
      "detail": null
    }
  ]
}
---

This happened around 25%

The second attempt to publish documentation moved further and failed in the same way at later page, around 55%. Would it be there's some rate limit, jira instability (what a surprise)? Is there a retry mechanism I could turn on for confluencebuilder?

[fizyk]

Changing to confluence_api_mode = 'v1' in configuration helped with this problem 🤔

[jdknight]

A 500 error is unexpected, but hard to know if it is an instance issue or if this extension may not be properly handling a use case (which Confluence does not have a graceful error code for it).

There is no configuration related to retrying this specific failed request. The only configuration-related option that could be attempted is trying to utilize confluence_publish_delay to pace requests (if the instance is not able to handle all the updates quickly and is not properly reporting the rate-limit codes; not an ideal approach).

If experienced in Python, you could try manipulating this extension's property update call to omit the retry for only 409; i.e. always retry twice and see how it reacts. If this helps, a change could be made to add retry support for properties when a 5xx error case is detected for this call.

[fizyk]

@jdknight I've attempted to publish docs on default v2 API settings today, and everything went smoothly.

BTW. I'm working with over 300 pages docs containing mermaid diagrams, and pushing it to cloud confluence.

Question: why confluecebuilder retries only on 409, and not the others? And would it made sense to introduce a retry_delay there as well?

[jdknight]

@fizyk, thanks for the update. And just to check, this is without any tweaks (i.e. it just worked this time) or did you try any of the suggested changes? For now, I am assuming the former.

why confluecebuilder retries only on 409

Well... there are a couple of retry scenarios by this extension. The specific 409 handling for that call is detailed in the code, but it is to deal with an assumed concurrency issue with Confluence. There have been other (older) scenarios where a crude retry was added for 500/etc. errors that were randomly observed by Confluence Cloud and self-hosted solutions based on observations/user reports, but the intent was never to design a complete retry-wrapping for all unexpected calls. Getting a 500 error was either a client making a bad call, or a server acting up -- and an ideal of retrying a bad request was not a preferred approach.

That being said, maybe this extension should permit a forced retry on all requests that report a 500 error (with the assumption that the target instance is having a temporary issue). It might not be too complex since we do support retries via Retry-After header hints.

[jdknight]

Changes have been introduced in https://github.com/sphinx-contrib/confluencebuilder/pull/984 to have this extension perform some additional API retries for certain error scenarios (e.g. 5XX errors). This applies to all API requests made. The hope is to help deal with large publication scenarios, where a single interim Confluence issue (such as a transaction error) can be retried on without having to start publishing again. Additional tailoring of this may be required over time.

These changes should be available next release (v2.6).

[jdknight]

v2.6 is now available on PyPI -- marking as closed.

It is recommended to try the new release without any explicit v1 API mode and please report any issues. Atlassian will drop support for v1 by the end of this year, and we hope to make sure this extension is in a good state before that time. Thanks again for the initial report.