Rate limiting and retries

This page provides details about rate limiting for app migration, and can help you understand how to anticipate rate limiting and manage how your app responds.

App migration platform

When calling app migration APIs we highly recommend that vendors implement exponential backoffs and retries to increase resilience to events affecting API call responses, such as:

• Rate-limiting (HTTP 429 responses)
• Atlassian infrastructure overload/downtime (HTTP 5xx errors)
• Network timeouts and connection failures
• Other unforeseen network issues preventing a successful response

It is vital that apps handle responses with the HTTP 429 Too Many Requests status code, the Retry-After header, HTTP 5xx server errors, and network timeouts.

Recommended retry strategy

Apps should treat receiving a 429 HTTP response, a Retry-After header, or HTTP 5xx errors as signals to retry the request after an appropriate delay. When implementing retries for app migration API calls, we recommend following these best practices:

When to retry

Retry requests in the following scenarios:

• HTTP 429 responses: Rate limiting - always respect the Retry-After header if present
• Network timeouts: When your HTTP client times out waiting for a response
  • HTTP 408 - Request Timeout
• HTTP 5xx errors: Server errors indicating temporary infrastructure issues, which include:
  • HTTP 500 - Internal Server Error
  • HTTP 502 - Bad Gateway
  • HTTP 503 - Service Unavailable
  • HTTP 504 - Gateway Timeout

Retry strategy details

1. Maximum retry count: Set a maximum number of retry attempts. We recommend 4 (for a total of 5 attempts).
2. Exponential backoff with jitter: Start with a base delay (for example, 1 second) and double the delay after each successive retry. Apply random jittering to avoid the thundering herd problem.
3. Respect Retry-After headers: When present in HTTP 429 responses, wait for the specified duration before retrying
4. Circuit breaker pattern: Consider implementing a circuit breaker to stop retrying after multiple consecutive failures

The following articles provide useful insights and techniques related to retry and backoff processing:

• Exponential backoff article in Wikipedia
• Error retries and exponential backoff in AWS
• Jira Cloud rate limiting and retry strategies

Cloud app

As with all web requests, you may receive HTTP 429 Too Many Requests responses for requests made to the app migration platform from the cloud app. When this occurs, check for the Retry-After header and implement exponential backoff as described above.

Server app

When calling the app migration platform methods from your server app, if the rate limit is exceeded you will receive a RuntimeException with an exception message App migration API rate limit exceeded.. You will get this new exception message for the following versions of Cloud migration assistant:

• Jira Cloud Migration Assistant version 1.6.9 or above
• Confluence Cloud Migration Assistant version 3.3.5 or above

Jira

During Jira app migration, apps may be subject to both a point-based 'quota' rate limit and a 'burst-rate' limit mechanism in which they may receive 429 responses. The documentation in Jira Cloud Platform rate limiting explains these mechanisms further.

Confluence

Required app migration header

To ensure your app migration code does not impact any other Confluence customer on the same infrastructure, you must include the HTTP header Migration-App with each request to any Confluence REST API. You can use any value with this header.

See an example

1
2
Migration-App: true

Current rate limits

The table below details the current rate limits in Confluence.

Managing requests

As with all web requests, you may receive HTTP 429 Too Many Requests responses.