Consultar o limite de conversas novas

GET /inbox/limits

Diz se a conta conectada pode iniciar conversas novas agora. Use para entender um envio recusado com provider_code: 463, ou antes de um envio em volume.

restriction só vem com restrição ativa: reachout_timelock (o WhatsApp travou a conta por um tempo, em geral pelo volume ou pela qualidade dos envios) ou new_chat_limit (a cota do ciclo acabou).
quota é a cota de conversas novas do ciclo atual, quando o WhatsApp a informa.

Se o WhatsApp não responder nenhuma das duas consultas, a rota responde 503 unavailable: tente de novo em instantes. Se responder só uma, sem restrição nela, vem can_start_chats: true (sem quota quando a da cota falhou). O resultado fica guardado por até 30 segundos.

Autenticação

[
  {
    "token": []
  }
]

{
  "token": {
    "name": "token",
    "type": "apiKey",
    "in": "header"
  }
}

Respostas

{
  "200": {
    "description": "Os limites de conversas novas da conta.",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "can_start_chats"
          ],
          "properties": {
            "can_start_chats": {
              "type": "boolean",
              "description": "Se a conta pode iniciar conversas novas agora.",
              "example": false
            },
            "restriction": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "code",
                "message"
              ],
              "description": "Só com restrição ativa.",
              "properties": {
                "code": {
                  "type": "string",
                  "enum": [
                    "reachout_timelock",
                    "new_chat_limit"
                  ],
                  "description": "`reachout_timelock`: trava temporária do WhatsApp; `new_chat_limit`: a cota do ciclo acabou. Com as duas, vem `reachout_timelock`.",
                  "example": "reachout_timelock"
                },
                "message": {
                  "type": "string",
                  "description": "Texto para pessoas.",
                  "example": "O WhatsApp restringiu temporariamente esta conta de iniciar novas conversas, em geral pelo volume ou pela qualidade dos envios."
                },
                "until": {
                  "type": "string",
                  "format": "date-time",
                  "description": "Até quando vale, quando o WhatsApp informa.",
                  "example": "2026-10-23T15:00:00Z"
                }
              }
            },
            "quota": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "used",
                "total"
              ],
              "description": "A cota de conversas novas do ciclo atual, quando o WhatsApp a informa.",
              "properties": {
                "used": {
                  "type": "integer",
                  "description": "Conversas novas iniciadas no ciclo.",
                  "example": 12
                },
                "total": {
                  "type": "integer",
                  "description": "O total do ciclo.",
                  "example": 250
                },
                "resets_at": {
                  "type": "string",
                  "format": "date-time",
                  "description": "Quando o ciclo recomeça.",
                  "example": "2026-10-24T00:00:00Z"
                }
              }
            }
          }
        },
        "examples": {
          "livre": {
            "summary": "Pode iniciar conversas",
            "value": {
              "can_start_chats": true,
              "quota": {
                "used": 12,
                "total": 250,
                "resets_at": "2026-10-24T00:00:00Z"
              }
            }
          },
          "travada": {
            "summary": "Trava temporária",
            "value": {
              "can_start_chats": false,
              "restriction": {
                "code": "reachout_timelock",
                "message": "O WhatsApp restringiu temporariamente esta conta de iniciar novas conversas, em geral pelo volume ou pela qualidade dos envios.",
                "until": "2026-10-23T15:00:00Z"
              }
            }
          }
        }
      }
    }
  },
  "401": {
    "description": "Token ausente ou inválido.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/OrkesioError"
        },
        "example": {
          "error": "unauthorized",
          "message": "Token inválido."
        }
      }
    }
  },
  "429": {
    "$ref": "#/components/responses/RateLimited"
  },
  "500": {
    "$ref": "#/components/responses/InternalError"
  },
  "501": {
    "$ref": "#/components/responses/CloudUnsupported"
  },
  "503": {
    "$ref": "#/components/responses/Disconnected"
  }
}

Estado: Disponível

Compatibilidade de canais

Canal	Compatível	Observação
WhatsApp (Web)	Sim
WhatsApp (API oficial)	Não	Só no WhatsApp Web.
Instagram	Não
Messenger	Não
Telegram	Não

Eventos que esta rota gera

Nenhum. Esta rota não gera evento no webhook (nem em GET /events): o resultado vem só na resposta.

Antes e depois (uazapi → Orkesio)

Na uazapi: GET /instance/wa_messages_limits.

/inbox/limits, com a resposta reescrita: can_start_chats, restriction (só com restrição ativa) e quota.
restriction.code em minúsculo: reachout_timelock (antes WHATSAPP_REACHOUT_TIMELOCK) e new_chat_limit (antes WHATSAPP_NEW_CHAT_LIMIT).
Saem os detalhes internos (provider, reachable, available, status, ote_status, mv_status, server_sent_at, enforcement_type, lookup_error, diagnostics_endpoint) e os textos em inglês; message vem em português.
Sem nenhuma resposta do WhatsApp, 503 unavailable; com uma só e sem restrição, can_start_chats: true (antes can_send_new_messages: null).

#/components/schemas/OrkesioError

{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Código estável do erro, em inglês e `snake_case`. Os de uso geral: `invalid_request` (400): pedido inválido: JSON malformado, campo desconhecido ou valor fora do permitido (o detalhe em `message`; o campo em `field`, quando é um só); `unauthorized` (401): `token` ou `admintoken` ausente ou inválido; `forbidden` (403): o token não pode fazer isso (no servidor de demonstração, por exemplo); `not_admin` (403): o WhatsApp recusou por falta de permissão no grupo ou na newsletter; `account_restricted` (403): o WhatsApp restringiu a conta de iniciar conversas novas (mandar para quem já conversa continua valendo; até quando, em `GET /inbox/limits`); `new_chat_limit` (403): a conta atingiu a cota do WhatsApp de conversas novas neste ciclo (veja `GET /inbox/limits`); os dois também no `error` de `OrkesioMessage` e de `message.status`, e não adianta repetir o envio; `payment_required` (403): na API oficial, a Meta recusou o envio por um problema no pagamento da conta do WhatsApp Business (erro 131042 da Meta); acerte a forma de pagamento no gerenciador da Meta, porque repetir não adianta; também no `error` de `OrkesioMessage` e de `message.status`; `whatsapp_rejected` (400): o WhatsApp recusou a mudança pedida (o campo, em `field`, quando é um só); `not_found` (404): o recurso não existe nesta inbox; `conflict` (409): o recurso já existe ou mudou (id em uso, inbox de outro canal); `inbox_not_paired` (409): a inbox ainda não conectou um número; `payload_too_large` (413): o corpo passou do limite; `canceled` e `expired`: só no `error` de `OrkesioMessage` e de `message.status` (envio cancelado antes de sair, ou que passou do prazo na fila); `rate_limited` (429): muitos pedidos; espere o `Retry-After`; `internal_error` (500): falha inesperada na api; tente de novo; `send_failed` (500): o envio falhou (o motivo em `message`); também no `error` de `OrkesioMessage` e de `message.status`; `unsupported_for_channel` (501): o canal da inbox não atende esta rota ou este tipo de mensagem; `meta_error` (502): a Meta recusou ou não respondeu; `disconnected` (503): a inbox está desconectada (sem sessão do WhatsApp, ou token do canal oficial vencido); `unavailable` (503 ou 504): o WhatsApp não respondeu a tempo, ou algo em andamento impede agora; tente de novo. Cada rota lista os códigos próprios dela (`outside_window`, `number_invalid`, `flow_invalid`...). A lista pode crescer: trate código desconhecido pelo status HTTP."
    },
    "message": {
      "type": "string",
      "description": "Descrição para pessoas (às vezes o texto do WhatsApp ou da Meta). Não compare o texto: use `error`."
    },
    "field": {
      "type": "string",
      "description": "O campo do pedido que causou o erro, quando é um só (por exemplo, o campo que o WhatsApp recusou num `PATCH`)."
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": true,
  "description": "O objeto de erro da Orkesio, o mesmo em todo lugar: o corpo das respostas de erro e o `error` de `OrkesioMessage`, `message.status` e `message.failed`. Algumas rotas juntam campos próprios (`request_id`, `errors`...)."
}

#/components/responses/RateLimited

{
  "description": "`rate_limited`: passou do limite de chamadas desta inbox (ou do admin); espere o tempo do header `Retry-After` e tente de novo.",
  "headers": {
    "Retry-After": {
      "description": "Segundos até poder chamar de novo.",
      "schema": {
        "type": "integer",
        "minimum": 1
      }
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OrkesioError"
      },
      "example": {
        "error": "rate_limited",
        "message": "Muitas requisições."
      }
    }
  }
}

#/components/responses/InternalError

{
  "description": "`internal_error`: falha inesperada na api (no banco, por exemplo); tente de novo.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OrkesioError"
      },
      "example": {
        "error": "internal_error",
        "message": "Falha inesperada."
      }
    }
  }
}

#/components/responses/CloudUnsupported

{
  "description": "`unsupported_for_channel`: o canal da inbox não atende esta rota (rota só do WhatsApp Web numa inbox oficial, ou rota da API oficial numa inbox do WhatsApp Web). O canal está em `Inbox.channel`.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OrkesioError"
      },
      "example": {
        "error": "unsupported_for_channel",
        "message": "Esta rota não está disponível no canal da inbox."
      }
    }
  }
}

#/components/responses/Disconnected

{
  "description": "`disconnected`: a inbox está desconectada do WhatsApp (a api esperou a sessão e tentou reconectar). `unavailable`: o WhatsApp não respondeu agora; tente de novo.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OrkesioError"
      },
      "example": {
        "error": "disconnected",
        "message": "Instância desconectada do WhatsApp."
      }
    }
  }
}

Guias relacionados

Visão geral · O que funciona em cada canal · O que muda da uazapi