Erro ‘Invalid Page ID’ do Notion em Requisições da API: Como Corrigir

Ao enviar uma requisição à API do Notion e receber um erro Invalid Page ID, sua integração não consegue encontrar a página ou banco de dados de destino. Esse erro aparece no corpo da resposta da API com código de status 404. A causa raiz é quase sempre uma incompatibilidade entre o ID fornecido e o formato esperado pelo Notion, ou a falta de permissão da integração para acessar o recurso. Este artigo explica por que o erro ocorre e fornece correções passo a passo para resolvê-lo permanentemente.

Por que a API do Notion Retorna o Erro Invalid Page ID

A API do Notion usa identificadores UUID versão 4 para páginas, bancos de dados e blocos. Cada ID de recurso é uma string hexadecimal de 32 caracteres no formato xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. Quando você passa um ID que não corresponde a esse padrão, a API rejeita a requisição com um erro Invalid Page ID.

Existem três cenários comuns que disparam esse erro:

1. Formato Incorreto do ID na Requisição

O ID copiado da URL de uma página do Notion pode conter caracteres extras ou estar truncado. Por exemplo, a URL https://www.notion.so/Minha-Pagina-abc123def456... inclui um slug de título que não faz parte do ID. Você deve extrair apenas o UUID de 32 caracteres após a última barra e antes de qualquer ponto de interrogação.

2. Integração Não Compartilhada com a Página de Destino

Mesmo que o ID esteja correto, a API retorna um erro 404 se sua integração não tiver acesso à página ou banco de dados específico. As integrações do Notion devem ser adicionadas explicitamente a cada recurso pelo menu Compartilhar. Isso é um descuido comum ao testar com novas páginas.

3. Uso de um ID de Bloco em vez de um ID de Página

A API do Notion distingue entre IDs de página, IDs de banco de dados e IDs de bloco. Se você passar um ID de bloco para um endpoint que espera um ID de página, a API retorna um erro Invalid Page ID. IDs de bloco também têm 32 caracteres, mas referenciam blocos de conteúdo individuais, não páginas de nível superior.

Passos para Corrigir o Erro Invalid Page ID

Siga estes passos em ordem. Teste sua chamada de API após cada passo para identificar a causa exata.

1. Verifique o formato do ID da página
   Abra a página do Notion no seu navegador. Copie a URL da barra de endereços. O ID é a string de 32 caracteres após a última barra e antes de qualquer ponto de interrogação. Deve se parecer com abc123def456abc123def456abc123de. Insira hífens após cada 8, 4, 4 e 4 caracteres: abc123de-f456-abc1-23de-f456abc123de. Use uma ferramenta validadora de UUID para confirmar que o formato está correto.
2. Adicione sua integração à página
   No aplicativo Notion, abra a página de destino. Clique no botão Compartilhar no canto superior direito. No campo Convidar, digite o nome da sua integração. Selecione-a na lista suspensa. Clique em Convidar. A integração agora tem acesso a esta página e seus filhos.
3. Verifique a URL do endpoint na sua chamada de API
   Certifique-se de estar usando o endpoint correto para o tipo de recurso. Para uma página, use https://api.notion.com/v1/pages/{page_id}. Para um banco de dados, use https://api.notion.com/v1/databases/{database_id}. Não use o endpoint de blocos para operações de nível de página.
4. Recupere o ID programaticamente
   Em vez de copiar o ID da URL, use o endpoint de Busca da API do Notion para obter o ID correto. Envie uma requisição POST para https://api.notion.com/v1/search com corpo vazio ou um filtro para o tipo de página. A resposta inclui o campo id no formato correto. Copie este ID diretamente para sua requisição.
5. Teste com uma requisição GET simples
   Envie uma requisição GET para https://api.notion.com/v1/pages/{page_id} usando o ID recuperado. Se a resposta retornar as propriedades da página, o ID está correto e a integração tem acesso. Se ainda receber o erro, verifique novamente o token de integração no cabeçalho Authorization.

Se o Notion Ainda Retornar Invalid Page ID Após a Correção

Token de Integração Inválido ou Expirado

Um token de integração expirado ou revogado causa um erro 401 Não Autorizado, mas alguns clientes de API podem interpretar isso erroneamente como um erro Invalid Page ID. Gere um novo token na página de Integrações do Notion em https://www.notion.so/my-integrations. Atualize seu cliente de API com o novo token e teste novamente.

Página Dentro de um Teamspace Privado

Se a página estiver em um teamspace privado, a integração deve ser adicionada ao próprio teamspace. Abra as configurações do teamspace, vá para Configurações e Membros > Teamspaces, selecione o teamspace, clique em Adicionar integrações e adicione sua integração. Em seguida, adicione novamente a integração à página individual conforme descrito no Passo 2.

ID de Banco de Dados Usado Onde se Espera um ID de Página

A API do Notion usa endpoints separados para páginas e bancos de dados. Se você passar um ID de banco de dados para o endpoint de páginas, receberá o erro Invalid Page ID. Confirme o tipo de recurso verificando o campo object na resposta da Busca. Para um banco de dados, o valor de object é database, não page.

ID de Página vs ID de Banco de Dados vs ID de Bloco no Notion: Principais Diferenças

Item	ID de Página	ID de Banco de Dados	ID de Bloco
Descrição	Identifica uma página única do Notion	Identifica um banco de dados do Notion	Identifica um bloco de conteúdo dentro de uma página
Endpoint	/v1/pages/{id}	/v1/databases/{id}	/v1/blocks/{id}
Como obter	URL da página ou endpoint de Busca	URL do banco de dados ou endpoint de Busca	Recuperar blocos filhos de uma página
Erro no endpoint errado	Invalid Page ID	Invalid Database ID	Invalid Block ID

Agora você sabe como identificar e corrigir o erro Invalid Page ID em requisições à API do Notion. Comece verificando o formato do ID e as permissões da integração na página de destino. Se o erro persistir, recupere o ID programaticamente usando o endpoint de Busca e confirme que está usando o endpoint correto para o tipo de recurso. Como verificação final, regenere seu token de integração se ele tiver expirado ou sido revogado.