# Retrieve the calling key's rate limit state

**GET /rate-limit**

What this key has left, on every budget that applies to it, measured
after this request has been counted.

Two budgets exist. `general` counts every request made with the key.
`audience` counts only the operations that return subscriber or
recipient email addresses, and is smaller: those operations are charged
to both budgets and have to pass both, so a key that has exhausted
`audience` can still call everything else.

Read this rather than inferring the whole picture from the `RateLimit-*`
headers. Those describe one budget, whichever is closest to exhaustion,
because a retry loop can only act on one number.

This operation is itself counted against the `general` budget. An
endpoint exempt from the limit would be the one call a client could make
in a loop for free.



## Servers
- Production. There is no separate sandbox host.
: https://api.usecommune.com (Production. There is no separate sandbox host.
)


## Authentication methods
- Api key


## Parameters
### Headers

- **Commune-Version** (string(date))
  The contract version this request is written against, as a release date
  (`YYYY-MM-DD`). Omitting the header pins the request to the version that
  was current when the API key was issued, so an integration keeps working
  when a newer version ships. An unknown value answers `400` with
  `invalid_version`.





## Responses
### 200
The current window, limit and remaining for this key.

#### Body: application/json (object)
- **object** (string)
  Always `rate_limit`.

- **limit** (integer)
  The `general` budget's limit, repeated for convenience.

- **remaining** (integer)
  Requests left on the `general` budget in this window.

- **window_seconds** (integer)
  The `general` budget's window length.

- **reset_at** (string(date-time))
  When the `general` budget's window resets.

- **policies** (array[object])
  Every budget this key is measured against, `general` first. A budget
  that does not apply to any operation the key may call is still
  listed, because what it counts is a property of the API rather than
  of the key.


### 401
No API key was presented, or the key is unknown, revoked or expired.

All four answer identically, down to the wording. Saying that a key was
revoked rather than never issued confirms to whoever is holding the
string that it was once real, which a legitimate caller does not need
and a thief should not get.

#### Headers

- **WWW-Authenticate** (string)
  The authentication scheme this API accepts. Always
  `Bearer realm="Commune API"`; there is no second scheme and no
  query-parameter fallback, because a credential that can travel in a
  URL ends up in access logs and referer headers.


#### Body: application/json (object)
- **error** (object)


### 429
Too many requests. Back off and retry after the interval named by the
`Retry-After` response header.

#### Headers

- **Retry-After** (integer)
  Seconds to wait before retrying.


#### Body: application/json (object)
- **error** (object)


### 500
Something failed inside Commune. The request may be retried.

#### Body: application/json (object)
- **error** (object)



[Powered by Bump.sh](https://bump.sh)