Announcement: 503 OVER_CAPACITY Responses



As of 2015-08-21 22:00 UTC, the Twitter Ads API is returning 503 SERVICE UNAVAILABLE with message OVER_CAPACITY whenever the Twitter Ads analytics backend exceeds its capacity due to a high volume of requests. If a 503 is returned for a request, the cost for the request will not impact the current rate limit status (x-cost-rate-limit-remaining response header).

Our team is working to ensure better availability and increased reliability on our stats endpoints, and we will be sharing updates on this effort as they’re available in this forum thread.

To let partners know when they should retry a query, we will soon add retry-after headers to all of our analytics endpoints that return a 503 SERVICE UNAVAILABLE. We will also be adding these to our non-analytics endpoints when they return a 503 in the coming weeks.

In the mean time, we recommend developers retry with exponential back-off using the x-cost-rate-limit-reset header value as the earliest next retry for analytics requests if they receive a 503 response from the Ads API. If there is a high volume of 503s, please delay queries for historical data.

Related Documentation:
Analytics Best Practices
Error Codes & Responses

"Over capacity" error
Analytics API service availability (HTTP 503 and very long-running async stats reports)


Since 2015-08-28 23:25 UTC we have seen stabilized service on our analytics endpoints due to performance improvements made on our backend. We ask all developers to implement the best practices and retry-logic outlined in this thread to ensure their service can handle these types of 503s with minimal impact.