EntrarTeste grátis

API · Atualizado em 12/10/2026

Erros, respostas e paginação da API

Entenda o formato de erro da API do Pipe, os códigos HTTP mais comuns, como paginar listas com cursor e como tratar cada falha.

Neste artigo
  1. Quando usar
  2. Formato do erro
  3. Códigos HTTP
  4. Paginação por cursor
  5. Formatos de data e telefone
  6. Resultado esperado
  7. Problemas comuns
  8. Boas práticas
  9. Próximos passos
  10. Perguntas frequentes

A API do Pipe usa o status HTTP de verdade: sucesso é 2xx e falha é 4xx ou 5xx. Nada de erro escondido dentro de uma resposta 200 nas rotas /v1. O corpo de qualquer erro tem sempre o mesmo formato.

Quando usar

Ao escrever o tratamento de erros da integração, e ao investigar uma chamada que não deu certo.

Formato do erro

{
  "error": {
    "code": "contact_phone_invalid",
    "message": "Informe um telefone no formato E.164 (ex.: +5511987654321).",
    "detalhe": {}
  }
}
CampoO que é
error.codeIdentificador estável do erro. Use este campo no seu código
error.messageTexto em português para mostrar a uma pessoa. Pode ser melhorado com o tempo
error.detalheInformações extras, quando existem (por exemplo o escopo que faltou ou o limite excedido)

Códigos HTTP

StatusQuando aconteceO que fazer
200, 201Deu certo. 201 indica que algo foi criadoLer o corpo
400Parâmetro ou corpo inválido, como data mal escrita, JSON inválido (json_invalid) ou campo obrigatório ausenteCorrigir a requisição
401not_authorized: chave ausente, inválida, revogada ou expiradaConferir a chave e o cabeçalho
403without_scope, ip_not_allowed, tenant_mismatch, financial_state_read_only ou chave de fluxo em rota de outro fluxoVer Escopos e permissões
404not_found: o recurso não existe ou está fora do fluxo da chaveConferir o id e o fluxo
409Conflito com o estado atual, como template_nao_aprovado, janela_fechada ou idempotency_conflictLer o code e ajustar
413corpo_grande: o corpo passa do limite (1 MB em JSON)Reduzir o corpo
422A requisição é válida, mas a regra de negócio recusou, como text_too_long ou location_invalidLer o code e ajustar
429rate_limited: limite de chamadas excedidoEsperar o tempo de Retry-After
500erro_interno: falha do PipeTentar de novo com espera; se persistir, avisar o suporte

Paginação por cursor

Rotas de lista devolvem os itens em data e o controle em page_info:

{
  "data": [ { "id": "..." } ],
  "page_info": {
    "has_next_page": true,
    "end_cursor": "eyJ2YWx1ZSI6IjIwMjYtMTAtMTJUMTI6MDA6MDAuMDAwWiIsImlkIjoiYjNhMSJ9"
  }
}

Parâmetros comuns:

ParâmetroO que faz
limitItens por página. Padrão 50, máximo 100. Valor menor que 1 ou que não é inteiro dá 400 limit_invalid
cursorO end_cursor da página anterior. Cursor inventado dá 400 cursor_invalid
order_byCampo de ordenação, com [asc] ou [desc], por exemplo criada_em[desc]. Cada rota aceita um conjunto de campos

Para percorrer tudo:

  1. Faça a primeira chamada sem cursor.
  2. Processe os itens de data.
  3. Se has_next_page for true, chame de novo com cursor igual ao end_cursor.
  4. Pare quando has_next_page for false.
curl -s "https://http.pipebr.app/v1/contacts?limit=100&cursor=$CURSOR" \
  -H "Authorization: Bearer $PIPE_CHAVE"

Algumas listas usam outro estilo, com pagina e porPagina (campanhas) ou page e perPage (histórico de tickets). Cada artigo indica qual vale.

Formatos de data e telefone

  • Instantes usam ISO 8601 em UTC, como 2026-10-12T14:30:00.000Z.
  • Filtros por dia nos relatórios usam AAAA-MM-DD, no fuso da conta.
  • Telefones seguem o formato internacional E.164, com + e o código do país, como +5511955550101.

Resultado esperado

Sua integração consegue distinguir erro seu (4xx) de falha do Pipe (5xx), repetir apenas o que vale repetir e percorrer listas grandes sem perder itens.

Problemas comuns

  • Lista que "repete" itens: não monte o cursor à mão. Use sempre o end_cursor que a API devolveu, sem alterar a ordenação entre as páginas.
  • 400 json_invalid com corpo certo: confira o cabeçalho Content-Type: application/json e a codificação UTF-8.
  • 422 em envio de mensagem: o code diz o motivo, como mensagem acima de 4096 caracteres (text_too_long) ou arquivo em formato que o WhatsApp não aceita.

Boas práticas

  • Trate 429 e 5xx com nova tentativa e espera crescente. Trate 4xx como erro de requisição, que repetir não resolve.
  • Registre o error.code e o message nos seus logs, nunca a chave.
  • Use Idempotency-Key nas escritas que você pode repetir.

Próximos passos

Perguntas frequentes

Como a API devolve um erro?

Com o status HTTP correto e um corpo JSON no formato { error: { code, message } }. Alguns erros trazem também o campo detalhe com informações extras.

Posso confiar no texto da mensagem de erro?

Use o texto para mostrar ao usuário ou registrar. Para decidir o que fazer, use o campo code, que é estável.

Como pego a próxima página de uma lista?

Se page_info.has_next_page for true, repita a chamada com cursor igual ao valor de page_info.end_cursor.

Qual o tamanho máximo de uma página?

100 itens. O padrão é 50. Pedir mais que 100 devolve 100.