Return Rate Limits

[justinormont]

Would it be possible to return the rate limit headers for every API call? X-RateLimit-Limit, X-RateLimit-Remaining, & X-RateLimit-Reset.

Currently, there's no method of checking the current rate limit values until the limit is hit.

Once the limit is reached the values are returned in the error:

masto.js/src/http/http-native-impl.ts

Lines 79 to 87 in c0c8ee0

	throw createError({
	statusCode: error.status,
	message: data?.error,
	details: data?.errorDescription,
	description: data?.details,
	limit: error.headers.get('X-RateLimit-Limit'),
	remaining: error.headers.get('X-RateLimit-Remaining'),
	reset: error.headers.get('X-RateLimit-Reset'),
	} as CreateErrorParams);

Alternatively, is there a way to get access to the HTTP response object, and get the headers directly?

[neet]

I'm wondering how to design our API to address this issue.

Currently, all methods in Masto.js return the JSON API response as is. I don't want to change this behaviour as I believe that most users are happy with this, but if we also want to return HTTP headers, we need to make the return value in the so-called "enveloped" object.

// 🙁
const { data, rateLimit } = await masto.v1.accounts.$select("123").fetch();

If anyone has any ideas, please comment.

[cheeaun]

For my use-case on Phanpy, would be useful to have a global event for exceeded rate limit. Writing code to check rate limit for every single API call is kinda… repetitive IMO.

RE: the return value, changing it would be a breaking change. Maybe introduce new methods? E.g. .fetchWithHeaders() that works the same as .fetch() but return "enveloped" object?

But looking at original post above, seems like maybe the expected code would be like this?:

try {
  const data = await masto.v1.accounts.$select("123").fetch();
  // Do something
} catch (e) {
  if (e.remaining <= 0) alert('Rate limit exceeded.');
  // Handle other errors
}

[neet]

Thanks for your opinion @cheeaun

would be useful to have a global event for exceeded rate limit

This could be a great solution because we don't need to add any new methods or changing the return type to an enveloped object... but in reality, rate limiting in Mastodon is not something global.

According to the docs, rate limit is computed within different layers. Generally, it is 300 calls per 5 minutes except for POST /api/v1/media DELETE /api/v1/statuses/:id``POST /api/v1/statuses/:id/unreblog POST /api/v1/accounts where they have a more strict limit.

This makes us to not able to implement rate limit to as a global event. It would be more precise and intuitive to let each method to have its own rate limit rather than something like this:

// pseudocode
const masto = createRestAPIClient(...)

masto.remainingCount
masto.resetDate
masto.addEventListener("rate_limit_exeed", (error) => ...)

fetchWithHeaders

You're correct... it is the most straightforward implementation, but honestly I don't want to add few dozens of additional methods to Masto.js only for this. Even though we now have moved to Proxy API, we still need to add type definitions for these new methods.

I think the relative costs for maintaining these new methods overweigh the advantages for developers who need rate limiting.

expected code would be like this

As @justinormont pointed out, we used to offer an error class dedicated for rate limit error. However, it wasn't that useful since it only tells you the remaining count after reaching to the limit. I remember I removed this error class at some point to reduce the bundle size.

[neet]

I'm thinking something like this but I'm not sure if I can actually implement it

// rate limits are saved in-memory inside the REST API client for each method
masto.v1.accounts.fetch.remaining
masto.v1.accounts.fetch.reset
masto.v1.accounts.fetch.limit

// you can still call the method
masto.v1.accounts.fetch()

[Isaw-w]

Any update?