Rate limiting

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

Rate limits exist to ensure the overall customer experience is not impacted by individual clients. While some features may have relaxed rate limits, all migration flows must be built to minimise the risk of hitting rate limits and robustly handle calls that are rate limited.

As a migration may create a significant number of calls to the core product, attention needs to be given to how to respond to rate limit conditions. This risk of rate limits can be reduced if clients ensure they use bulk APIs where available to reduce the overall call rate, use efficient calls, and cache stable data where feasible.

App migration platform

When calling app migration APIs vendors must 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

App migrations 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
5. Logging: Log the request, the rate limit reason, and rate limit headers, to help with diagnosing rate limit causes.

Exhausting retry attempts or triggering a circuit breaker will in most cases cause a migration failure. Consideration should be given to reducing concurrency and slowing the request rate prior to failing the migration.

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.

When migrations are generating a large call rate over an extended period of time, vendors should also reduce call concurrency when rate limits are encountered. If a number of workers are concurrently performing the migration, the number of workers should be reduced when consistent 429 Too Many Requests responses are encountered.

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.. Implement exponential backoff to handle these rate limits.

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.

Additional Links

The following articles provide useful insights and techniques:

• Exponential backoff article in Wikipedia
• Jira Cloud rate limiting and retry strategies
• Migrate entity properties with the Bulk API