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

# Remover número extra (On Demand)

> Agenda a redução de N slot(s) de número extra pago para o PRÓXIMO ciclo — o inverso de POST. Requer uma key com escopo de TENANT. SEM estorno do ciclo corrente; o valor menor é cobrado a partir da próxima virada. Excluir ou purgar um número NÃO reduz a capacidade paga — este é o único caminho. Retorna 409 NUMBER_LIMIT_EXCEEDED se a redução deixaria o limite abaixo dos números conectados, e 409 NOT_APPLICABLE_FOR_PLAN no Pay As You Go (que já cobra só os números que continuam conectados).

**Requer uma key com escopo de tenant.**



## OpenAPI

````yaml openapi.pt.json DELETE /v1/subscription/extra-numbers
openapi: 3.1.0
info:
  title: API Pilot Status
  version: 1.0.0
  license:
    name: Pilot Status Terms of Service
    url: https://pilotstatus.com.br/terms
  description: >-
    API REST pública do Pilot Status. Autentique com o header `x-api-key:
    ps_...` (ou `x-api-key-id`). Base URL: https://pilotstatus.com.br
servers:
  - url: https://pilotstatus.com.br
security:
  - apiKey: []
  - apiKeyId: []
paths:
  /v1/subscription/extra-numbers:
    delete:
      tags:
        - Subscription
      summary: Remover número extra (On Demand)
      description: >-
        Agenda a redução de N slot(s) de número extra pago para o PRÓXIMO ciclo
        — o inverso de POST. Requer uma key com escopo de TENANT. SEM estorno do
        ciclo corrente; o valor menor é cobrado a partir da próxima virada.
        Excluir ou purgar um número NÃO reduz a capacidade paga — este é o único
        caminho. Retorna 409 NUMBER_LIMIT_EXCEEDED se a redução deixaria o
        limite abaixo dos números conectados, e 409 NOT_APPLICABLE_FOR_PLAN no
        Pay As You Go (que já cobra só os números que continuam conectados).


        **Requer uma key com escopo de tenant.**
      operationId: delete_subscription_extra-numbers
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                quantity:
                  type: number
                  description: Quantos slots de número extra devolver (default 1).
                  example: '1'
      responses:
        '200':
          description: Removeu 1 slot
          content:
            application/json:
              example:
                success: true
                charged: true
                plan: ON_DEMAND
                paidExtraNumbers: 1
                maxNumbers: 1
                proratedTotal: 0
        '400':
          description: >-
            Payload ou parâmetros inválidos — ou `INVALID_BODY` quando o corpo
            não é um JSON válido: nada é cobrado nem agendado. Corpo vazio
            continua significando `quantity = 1`
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: string
              examples:
                validation:
                  summary: Erro de validação
                  value:
                    error: quantity deve ser um inteiro >= 1
                invalidBody:
                  summary: Corpo não é um JSON válido
                  value:
                    error: >-
                      The request body is not valid JSON | O corpo da requisição
                      não é um JSON válido
                    code: INVALID_BODY
        '401':
          description: Header `x-api-key` / `x-api-key-id` ausente ou inválido
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: string
              example:
                error: Unauthorized
        '403':
          description: Key de número usada em endpoint de tenant
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: string
              example:
                error: Number-scoped keys cannot call tenant endpoints
                code: NUMBER_SCOPE_NOT_ALLOWED
        '409':
          description: >-
            Redução impossível: o limite ficaria abaixo dos números conectados
            (`NUMBER_LIMIT_EXCEEDED`), ou o plano não tem capacidade paga a
            devolver (`NOT_APPLICABLE_FOR_PLAN`, Pay As You Go).
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: string
                    enum:
                      - NUMBER_LIMIT_EXCEEDED
                      - NOT_APPLICABLE_FOR_PLAN
                  plan:
                    type: string
                    description: >-
                      Só em NOT_APPLICABLE_FOR_PLAN: o plano que não tem
                      capacidade paga a devolver.
                    example: PAY_AS_YOU_GO
                  currentNumberCount:
                    type: number
                  maxNumbers:
                    type: number
              example:
                error: >-
                  Você tem 2 número(s) conectado(s); remover 2 deixaria o limite
                  em 0. Desconecte números antes de remover slots pagos.
                code: NUMBER_LIMIT_EXCEEDED
                currentNumberCount: 2
                maxNumbers: 0
        '429':
          description: Limite de taxa excedido
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: string
              example:
                error: Too many requests
components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: Sua chave de API ps_
    apiKeyId:
      type: apiKey
      in: header
      name: x-api-key-id
      description: Id da chave de API (alternativa ao x-api-key)

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.