Erros de contato

Tabela de erros

HTTP	error	Quando
400	invalid_contact_id	contact_id não bate com ^ct_[0-9a-f]{32}$
400	invalid_cursor	Cursor opaco corrompido
402	contact_quota_exceeded	Retornado pelo envio de mensagem (não pelos endpoints de contato) quando a cota de contatos distintos do ciclo do número já foi atingida
401	not_authenticated	A chave de API está ausente, inválida ou revogada
403	insufficient_scope	A chave de API não tem o escopo exigido pela rota: contacts:read para listagem, detalhe e foto; contacts:write para atualização (a resposta inclui required_scope)
404	contact_not_found	O contato não existe, pertence a outra organização ou a outro número (o {ref} da rota)
404	number_not_found	O {ref} da rota não corresponde a nenhum número da conta (vale para /contacts, /contacts/{id}, /contacts/quota e as demais sub-rotas)
400	invalid_number_id	O valor na URL começa com num_, mas não é um id de número válido.
404	contact_picture_unavailable	Caso raro: falha ao gerar a URL pré-assinada da foto. A ausência de foto (sem armazenamento, envio da foto falhou, contato sem foto) não retorna 404: veja Foto de perfil
422	validation_error	Um parâmetro de consulta não passou na validação, por exemplo limit fora do intervalo de 1 a 200. A resposta traz details.errors com os campos rejeitados
429	refresh_rate_limited	Limite de atualizações por minuto atingido
500	internal_error	Erro inesperado no servidor

Exemplo de resposta 402

Retornado quando você tenta falar pelo Turbo Notify com um contato que passaria a ser contado no ciclo atual (um contato novo ou um contato recorrente ainda não contado neste ciclo) e a cota de contatos distintos do ciclo já está esgotada.

Status HTTP: 402

{
  "error": "contact_quota_exceeded",
  "message": "Distinct-contacts quota exceeded for tier SOLO (100/100 this cycle)",
  "details": {
    "quota": 100,
    "used": 100,
    "resets_at": "2026-08-01T00:00:00Z",
    "tier": "SOLO"
  }
}

O que fazer: faça upgrade do plano. Ao contrário do 429, o 402 não tem Retry-After: repetir o envio não resolve. A cota só volta quando o ciclo de faturamento fecha (em resets_at) ou quando o plano muda.

Diferença entre 402 e 429

	402 Payment Required	429 Too Many Requests
Significado	Limite do plano: faça upgrade	Limite de velocidade: tente de novo depois
Cabeçalho	—	Retry-After: <segundos>
Quando volta	No fim do ciclo de faturamento (resets_at) ou com upgrade	Em segundos ou minutos
Origem	Cota do ciclo	Proteção contra rajadas

Veja também: Cota e uso.