Respostas e erros

A API retorna JSON em UTF-8. Use o código HTTP para identificar o resultado da requisição e leia o corpo para obter os dados ou o motivo do erro.

Formato das respostas

Em uma resposta de sucesso, status é ok e o resultado está em dados:

{"status": "ok", "dados": {}}

Em uma resposta de erro, status é erro e mensagem descreve o problema:

{
  "status": "erro",
  "mensagem": "O parâmetro por_pagina deve ser um número inteiro de 1 a 100."
}

As mensagens da API são em português. Registre-as para diagnóstico, mas baseie o tratamento automático no código HTTP, pois o texto pode mudar.

Códigos HTTP e tratamento

Código	Significado	Como tratar
200	Operação concluída.	Leia dados.
201	Link criado.	Guarde dados.id e dados.url_curta.
400	Parâmetro ausente, desconhecido ou inválido.	Corrija a requisição conforme a referência do endpoint e a mensagem.
401	Token ausente, inválido, vencido ou revogado.	Confira o cabeçalho e a situação do token no painel.
403	Acesso não autorizado pelo plano, pela conta ou pelo token.	Confira o plano e o escopo em Autenticação.
404	Endpoint ou recurso não encontrado no escopo do token.	Confira o caminho, o ID e o acesso ao link.
405	Método HTTP incorreto.	Use o método indicado no cabeçalho Allow.
409	Código de link já utilizado ou reservado.	Escolha outro código.
413	Corpo da requisição maior que 16 KB.	Reduza o conteúdo enviado.
415	Tipo de conteúdo incompatível.	Envie JSON com Content-Type: application/json.
429	Cota diária ou limite por minuto atingido.	Aguarde o tempo indicado em Retry-After.
500 ou 503	Falha ou indisponibilidade do serviço.	Aguarde antes de tentar novamente.

Repetição de requisições

Para 429, respeite Retry-After. Para falhas temporárias, como 500 e 503, use um intervalo crescente entre tentativas. Erros de validação ou autorização precisam ser corrigidos antes de repetir.

Se uma requisição de criação ficar sem resposta, o link pode ter sido criado. Pesquise o destino em Listar links antes de reenviar para evitar duplicações.

Repetir uma edição com os mesmos valores mantém o resultado. Repetir uma exclusão retorna 404 se o link já tiver sido removido.

Datas e horários

Datas sem horário usam AAAA-MM-DD, como 2026-10-04. Datas com horário usam ISO 8601 e incluem o fuso, como 2026-10-04T14:32:10-03:00. Considere o fuso informado ao exibir ou comparar horários.