Errors will return with standard HTTP status codes. Status codes are as follows:
  • 1xx: Informational - Communicates transfer protocol-level information.
  • 2xx: Success - The request was successful.
  • 3xx: Redirection - The client must take some additional action to complete the request.
  • 4xx: Client Error - Failed request due to client error.
  • 5xx: Server Error - Failed request due to server error.

​
200 Success

A successful request was made.

​
400 Bad Request

A 400 Bad Request error means that the server was unable to proceed with the request. The most common cause of the error is bad syntax in the request URL or body.

​
401 Unauthorized

401 Unauthorized errors are usually caused by a problem in the request header of your API call, i.e. you didn’t use a valid API key to make the API call.

​
403 Access Denied

When your application makes an API call with your API key and the request is not allowed. A 403 might also be returned if the User Profile is suspended.

​
404 Resource Not Found

This error occurs when your application tries to call an API or fetch an entity that does not exist.

​
405 Method Not Allowed

This error indicates that the HTTP protocol methods in your request are not supported. Check the documentation for the API to see supported methods.

​
429 Rate Limit

​
User Profile Rate Limits

Each User Profile has a rate limit of 300 API requests per 5-minute interval. You can monitor your rate limit usage through the response headers:
  • x-ratelimit-max: Shows your maximum allowed requests per 5-minute period
  • x-ratelimit-count: Displays how many requests you’ve made in the current 5-minute period
We recommend checking for 429 error code responses. If you see a 429 error, you’ve reached your rate limit. Repeated attempts to exceed the rate limit may result in the User Profile being suspended.Learn more about handling rate limits for multiple user profiles.

​
X Analytics Rate Limits

X (formerly Twitter) analytics API requests have specific rate limits that vary by account type: Daily Limits:
  • Business User Profiles: 1,000 API requests per 24-hour period.
  • Premium User Profiles: 500 API requests per 24-hour period.
Monthly Limits: These limits reset on the 2nd of each month at 00:00 UTC:
  • Business Plan accounts: 100,000 requests per month.
  • Premium Plan accounts: 5,000 requests per month.
Once you reach either your daily or monthly limit, additional requests will return a 429 error until the respective period resets. For increased X analytics rate limits, please contact your Ayrshare account representative.

​
User Profile Deletion Rate Limits

You may delete 8 user profiles per second. Please stagger API calls if you need to bulk delete.

​
Rate Limit Protection and Suspension Policy

To protect our system integrity, we implement automatic suspension if a User Profile exceeds rate limits too frequently. Here’s how it works: When you make API requests, you must carefully manage the 5-minute window. For example, if you make 200 requests in one minute, you’ll need to wait four more minutes before making additional requests. Any requests during this waiting period will trigger a 429 error response. If a User Profile accumulates 1,000 rate limit violations (429 errors) within a 24-hour period, the profile will be automatically suspended. After a 5-minute waiting period expires, you can resume making requests up to the standard limit of 250 per 5-minute window.

​
500 Internal Server Error

A 500 Internal Server Error indicates that Ayrshare is experiencing an internal error or processing failed.