# Check a rate limit (/docs/api-reference/risk/check-risk-limit)

Takes `cost` tokens (default 1) from `key`'s share of one of your buckets and says whether to let the request through: a 200 either way, with `allowed`. Denied requests take nothing. Each key has its own bucket of `burst` tokens refilling at `limit` per `period_seconds` (GCRA, the algorithm coss.com limits its own API with). coss.com keeps only a keyed hash of `key`. While coss.com can't count, the bucket's `on_failure` answers and `degraded` is true.

`POST https://api.coss.com/v1/risk/limits`

Authenticate with your API key as a bearer token (`Authorization: Bearer coss_test_…`). Responses are JSON with snake_case fields; errors are `{ error: { type, code, message, param?, issues?, request_id } }` (https://coss.com/docs/api-reference/errors.md).

## Headers

- `Idempotency-Key` (string, 1-256 characters): Makes retries safe: a repeated allowed check with the same key is answered again without taking more tokens, for an hour. 1-256 characters.

## Request body

- `bucket` (string, required): The bucket's name.
- `key` (string, required, 1-512 characters): Who or what is limited: a user id, an email address, an IP address… coss.com keeps only a keyed hash of it.
- `cost` (integer, 1-1000000): Tokens this request takes. Default 1.

## Example request

TypeScript (the `coss` package):

```ts
import { Coss } from "coss";

const coss = new Coss({
  apiKey: process.env.COSS_API_KEY,
  baseUrl: "https://api.coss.com",
});

const { data, error } = await coss.risk.limit({
  bucket: "password_reset",
  key: "ada@example.com",
}, {
  idempotencyKey: "welcome-user-123",
});
```

HTTP:

```sh
curl -X POST "https://api.coss.com/v1/risk/limits" \
  -H "Authorization: Bearer $COSS_API_KEY" \
  -H "Idempotency-Key: welcome-user-123" \
  -H "Content-Type: application/json" \
  -d '{
  "bucket": "password_reset",
  "key": "ada@example.com"
}'
```

Python:

```python
from coss import Coss

client = Coss()  # api_key= or COSS_API_KEY

client.risk.limit(
    idempotency_key="welcome-user-123",
    bucket="password_reset",
    key="ada@example.com",
)
```

Go:

```go
import (
	"context"

	coss "github.com/cosscom/coss-go"
	cossclient "github.com/cosscom/coss-go/client"
)

client := cossclient.NewClient() // option.WithAPIKey(…) or COSS_API_KEY

request := &coss.CheckRiskLimitRequest{
    IdempotencyKey: coss.String(
        "welcome-user-123",
    ),
    Bucket: "password_reset",
    Key: "ada@example.com",
}
client.Risk.Limit(
    context.TODO(),
    request,
)
```

Ruby:

```ruby
require "coss"

client = Coss::Client.new # api_key: or COSS_API_KEY

client.risk.limit(
  idempotency_key: "welcome-user-123",
  bucket: "password_reset",
  key: "ada@example.com"
)
```

PHP:

```php
<?php

use Coss\Coss;
use Coss\Risk\Requests\CheckRiskLimitRequest;

$client = new Coss(); // apiKey: or COSS_API_KEY

$client->risk->limit(
    new CheckRiskLimitRequest([
        'idempotencyKey' => 'welcome-user-123',
        'bucket' => 'password_reset',
        'key' => 'ada@example.com',
    ]),
);
```

Java:

```java
import com.coss.Coss;
import com.coss.resources.risk.requests.CheckRiskLimitRequest;

Coss client = Coss.builder().build(); // .apiKey(…) or COSS_API_KEY

client.risk().limit(
    CheckRiskLimitRequest
        .builder()
        .bucket("password_reset")
        .key("ada@example.com")
        .idempotencyKey("welcome-user-123")
        .build()
);
```

.NET:

```csharp
using Coss;

var client = new CossClient(); // apiKey: or COSS_API_KEY

await client.Risk.LimitAsync(
    new CheckRiskLimitRequest
    {
        IdempotencyKey = "welcome-user-123",
        Bucket = "password_reset",
        Key = "ada@example.com",
    }
);
```

## Response 200

The answer for this request.

- `object` ("risk_limit", required)
- `bucket` (string, required): The bucket's name.
- `allowed` (boolean, required): Whether to let the request through. Denied requests take no tokens.
- `limit` (integer, required): The bucket's size (`burst`).
- `remaining` (integer, required): Tokens left for this key.
- `reset_ms` (integer, required): Milliseconds until the key's bucket is full again.
- `retry_after_ms` (integer | null, required): When denied: milliseconds until the same request would be allowed; `null` when it never would (`cost` above the bucket's size). 0 when allowed.
- `degraded` (boolean, required): coss.com couldn't count (its store was unavailable): `allowed` is the bucket's `on_failure`.

Example:

```json
{
  "object": "risk_limit",
  "bucket": "password_reset",
  "allowed": true,
  "limit": 5,
  "remaining": 4,
  "reset_ms": 720000,
  "retry_after_ms": 0,
  "degraded": false
}
```

## Errors

- `400`: The body is not valid JSON (`invalid_json`) or the `Idempotency-Key` header is invalid (`invalid_idempotency_key`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).
- `401`: The API key is missing, invalid, revoked or expired (`authentication_error`).
- `403`: The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).
- `404`: No bucket with this name exists in the API key's environment (`not_found`).
- `413`: The request body is larger than 5 MB (`payload_too_large`).
- `415`: The body is not sent as `application/json` (`unsupported_media_type`).
- `422`: The body failed validation (`validation_error`, see `issues`).
- `429`: Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).
- `500`: Unexpected server error (`api_error` / `internal_error`).
- `503`: The API key could not be verified right now; retry (`service_unavailable`).