> ## Documentation Index
> Fetch the complete documentation index at: https://docs.limitem.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Ratelimit

> Apply a rate limit for one identifier. The product, basically.

<Note>
  `Content-Type` must be `application/json`. `application/json; charset=utf-8` is fine. If Limitem is down, a 200 can still come back with `degraded: true` — that's fail-open.
</Note>


## OpenAPI

````yaml openapi.json POST /limit
openapi: 3.0.3
info:
  title: Limitem Rate Limiting API
  version: v2026.8.23
  description: Contiguity's internal rate limiter. One customer. One interesting endpoint.
servers:
  - url: https://api.limitem.com
    description: Production
security: []
paths:
  /limit:
    post:
      summary: POST /limit
      description: Apply a rate limit for one identifier. The product, basically.
      operationId: limit
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LimitRequest'
            example:
              namespace: contiguity-api
              product: outbound_sms
              identifier: user:123
              limit: 100
              duration: 3600
              algorithm: fixed-window
      responses:
        '200':
          description: Request allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LimitAllowed'
              example:
                id: req_xxxxxxxxxxxxxxxx
                timestamp: 1705320000000
                api_version: v2026.8.23
                object: rate_limit
                data:
                  allowed: true
                  namespace: contiguity-api.outbound_sms
                  identifier: user:123
                  limit: 100
                  remaining: 99
                  reset_time: 1705323600
                  count: 1
                  algorithm: fixed-window
                  _request:
                    success: true
                    processing_time_ms: 12
        '400':
          description: Bad body. Limit, duration, or a required field is wrong.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                id: err_xxxxxxxxxxxxxxxx
                timestamp: 1705320000000
                api_version: v2026.8.23
                object: error
                data:
                  error: Bad Request
                  status: 400
        '401':
          description: Missing or invalid token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                id: err_xxxxxxxxxxxxxxxx
                timestamp: 1705320000000
                api_version: v2026.8.23
                object: error
                data:
                  error: Unauthorized
                  status: 401
        '429':
          description: This identifier is over the limit.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LimitBlocked'
              example:
                id: err_xxxxxxxxxxxxxxxx
                timestamp: 1705320000000
                api_version: v2026.8.23
                object: error
                data:
                  error: Rate limit exceeded
                  status: 429
                  namespace: contiguity-api.outbound_sms
                  identifier: user:123
                  limit: 100
                  remaining: 0
                  reset_time: 1705323600
                  retry_after: 42
                  _request:
                    success: false
                    processing_time_ms: 8
        '500':
          description: Something broke on our side.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                id: err_xxxxxxxxxxxxxxxx
                timestamp: 1705320000000
                api_version: v2026.8.23
                object: error
                data:
                  error: Internal server error
                  status: 500
      security:
        - bearerAuth: []
components:
  schemas:
    LimitRequest:
      type: object
      required:
        - namespace
        - identifier
        - limit
        - duration
      properties:
        namespace:
          type: string
          minLength: 1
          maxLength: 256
          description: Namespace for the limit.
          example: contiguity-api
        product:
          type: string
          minLength: 1
          maxLength: 128
          description: Optional product. Slugified and appended as `namespace.product`.
          example: outbound_sms
        identifier:
          type: string
          minLength: 1
          maxLength: 512
          description: Who you're limiting.
          example: user:123
        limit:
          type: number
          minimum: 1
          maximum: 1000000
          description: Requests allowed in the window.
          example: 100
        duration:
          type: number
          minimum: 1
          maximum: 31536000
          description: Window length in seconds. `1`–`31536000` (one year).
          example: 3600
        algorithm:
          type: string
          enum:
            - fixed-window
            - sliding-window
            - token-bucket
            - leaky-bucket
          default: fixed-window
          description: Rate limiting algorithm.
          example: fixed-window
    LimitAllowed:
      type: object
      required:
        - id
        - timestamp
        - api_version
        - object
        - data
      properties:
        id:
          type: string
          example: req_xxxxxxxxxxxxxxxx
        timestamp:
          type: number
          example: 1705320000000
        api_version:
          type: string
          example: v2026.8.23
        object:
          type: string
          example: rate_limit
        data:
          type: object
          required:
            - allowed
            - namespace
            - identifier
            - limit
            - remaining
            - reset_time
            - count
            - algorithm
            - _request
          properties:
            allowed:
              type: boolean
              description: Always `true` on 200.
            namespace:
              type: string
              description: Effective namespace, including product.
            identifier:
              type: string
            limit:
              type: number
            remaining:
              type: number
              description: Requests left after this one.
            reset_time:
              type: number
              description: Unix timestamp (seconds). Meaning depends on the algorithm.
            count:
              type: number
              description: Current request count in this window.
            algorithm:
              type: string
            degraded:
              type: boolean
              description: Only present when Limitem failed open.
            _request:
              $ref: '#/components/schemas/RequestMeta'
    Error:
      type: object
      required:
        - id
        - timestamp
        - api_version
        - object
        - data
      properties:
        id:
          type: string
          example: err_xxxxxxxxxxxxxxxx
        timestamp:
          type: number
        api_version:
          type: string
        object:
          type: string
          example: error
        data:
          type: object
          required:
            - error
            - status
          properties:
            error:
              type: string
            status:
              type: number
    LimitBlocked:
      type: object
      required:
        - id
        - timestamp
        - api_version
        - object
        - data
      properties:
        id:
          type: string
          example: err_xxxxxxxxxxxxxxxx
        timestamp:
          type: number
        api_version:
          type: string
        object:
          type: string
          example: error
        data:
          type: object
          required:
            - error
            - status
            - namespace
            - identifier
            - limit
            - remaining
            - reset_time
            - retry_after
            - _request
          properties:
            error:
              type: string
              example: Rate limit exceeded
            status:
              type: number
              example: 429
            namespace:
              type: string
            identifier:
              type: string
            limit:
              type: number
            remaining:
              type: number
            reset_time:
              type: number
            retry_after:
              type: number
              description: >-
                Seconds to wait before this identifier has room again. Never
                negative.
            _request:
              $ref: '#/components/schemas/RequestMeta'
    RequestMeta:
      type: object
      required:
        - success
        - processing_time_ms
      properties:
        success:
          type: boolean
          description: Whether request processing succeeded.
        processing_time_ms:
          type: number
          description: Time taken to process this request, in milliseconds.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: limitem_sk
      description: 'Contiguity token. `Authorization: Bearer limitem_sk_...`'

````