> ## Documentation Index > Fetch the complete documentation index at: https://help.ciarem.ai/llms.txt > Use this file to discover all available pages before exploring further. # Erros, limites e paginação > O vocabulário de erros, os limites de uso, a paginação e como a API evolui. ## Erros Os erros usam códigos de status convencionais com um `detail` legível por máquina: | Status | Significado | Exemplo de `detail` | | ------ | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | 400 | A solicitação está endereçada errado | `{"code": "invalid_channel", …}`, `{"code": "channel_id_required", …}` | | 401 | A chave está ausente, não existe ou foi revogada | `"missing_bearer_token"`, `"invalid_api_key"` | | 402 | Saldo do WhatsApp insuficiente para o que você pediu | `{"code": "wa_insufficient_balance", …}` | | 403 | Credencial válida, mas não permitida aqui | `"api_key_required"`, `"scale_plan_required"`, `"trial_expired"`, `"subscription_required"` — veja [Autenticação](/api-reference/authentication) | | 404 | O recurso não existe na sua organização | `"not_found"`, `{"code": "contact_not_found", …}` | | 409 | Conflito | `{"code": "duplicate_contact", …}`, `{"code": "messaging_limit_exceeded", …}` | | 422 | O corpo da solicitação falhou na validação | mensagens por campo, ou `{"code": …}` | | 429 | Acima do limite de uso | `"rate_limited"` — tente novamente conforme o cabeçalho `Retry-After` | Erros estruturados sempre carregam um `code` estável sobre o qual você pode ramificar; as chaves adicionais (como `conflicting_contact_id` em um contato duplicado) fornecem o necessário para resolver. Cada formato de erro está publicado na [referência da API](/api-reference/openapi). ### Enviar um modelo `POST /v1/templates/{id}/send` recusa a solicitação **inteira** em vez de enfileirar parte dela, então uma recusa nunca deixa você com o envio pela metade nem custa nada. Os códigos que vale ramificar: | `code` | Status | O que fazer | | ---------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `channel_id_required` | 400 | Sua conta tem mais de um número do WhatsApp. Escolha um — a resposta lista os ids elegíveis. | | `invalid_channel` | 400 | O `channel_id` não é um número ativo da conta do WhatsApp deste modelo. | | `template_not_sendable` | 409 / 422 | O modelo não está `APPROVED` (409), ou nunca poderá ser enviado — o botão de um cartão do carrossel não tem como ser preenchido (422). | | `messaging_limit_exceeded` | 409 | O lote é maior do que o que resta do limite móvel de 24 horas do WhatsApp. `remaining` diz quantos caberiam. | | `wa_insufficient_balance` | 402 | Recarregue a carteira do WhatsApp; nada foi enfileirado. | | `contact_not_found` | 404 | `index` diz qual destinatário. | | `missing_variables` | 422 | `tokens` lista o que falta para aquele destinatário — incluindo `header.media` quando o modelo tem cabeçalho de mídia e você não enviou uma URL. | | `unknown_variables` / `unknown_url_suffixes` | 422 | Você enviou uma chave que o modelo não usa. Ela seria descartada em silêncio, então recusamos. | | `media_too_large` / `media_type_mismatch` / `media_fetch_failed` | 422 | Nós baixamos a `header_media_url`; ela precisa estar publicamente acessível, ser do tipo do cabeçalho e caber no limite de tamanho do WhatsApp para aquele tipo (5 MB imagem, 16 MB vídeo, 100 MB documento). | | `idempotency_key_in_flight` | 409 | Uma solicitação anterior com esta `Idempotency-Key` ainda está sendo enfileirada. | `GET /v1/templates/{id}/send-requirements` diz o que um modelo precisa **antes** de enviar, então a maioria destes nunca precisa acontecer. ## Limites de uso Cada organização tem um orçamento compartilhado de **20 solicitações por segundo** entre todas as suas chaves — **5 por segundo** durante o teste gratuito. Acima do orçamento, as solicitações retornam `429` com um cabeçalho `Retry-After` (segundos; sempre `1`, porque a janela é de um segundo). Cada resposta — inclusive o `429` — carrega o seu orçamento atual, para você dosar sem contar chamadas por conta própria: | Cabeçalho | | | ----------------------- | ---------------------------------------------------------- | | `X-RateLimit-Limit` | Solicitações permitidas por janela. | | `X-RateLimit-Remaining` | Solicitações restantes na janela atual. | | `X-RateLimit-Reset` | Quando a janela reinicia, como timestamp Unix em segundos. | Leia `X-RateLimit-Remaining` e reduza o ritmo conforme ele se aproxima de zero, em vez de correr até o `429`. Se a sua integração realmente precisar de mais, fale com a gente. Uma solicitação é uma solicitação, não importa quanto ela faça. `POST /v1/templates/{id}/send` conta uma vez só, leve um destinatário ou cem — então agrupar destinatários em um único envio é a forma mais barata de ficar dentro do orçamento. O que limita o volume real de mensagens é o próprio limite móvel de 24 horas do WhatsApp, não este. ## Repetir com segurança `POST /v1/templates/{id}/send` aceita um cabeçalho **`Idempotency-Key`**. Envie a mesma chave de novo dentro de 24 horas e você recebe a campanha original em vez de um segundo envio — que é o que você quer depois de um timeout, quando realmente não dá para saber se a solicitação chegou. Use uma chave nova para cada envio distinto. ## Paginação Os endpoints de listagem retornam: ```json theme={null} { "items": [ … ], "next_cursor": "cnt_…" } ``` Passe `next_cursor` de volta como `?cursor=` para buscar a próxima página; um cursor `null` significa que você chegou ao fim. Os cursores são opacos — não os interprete. As listas de propriedades e etapas do funil não são paginadas: retornam o conjunto completo, sem `next_cursor`. ## Compatibilidade Esta é uma API jovem e em rápida evolução — espere que ela mude. Dois hábitos mantêm sua integração estável: * A maioria das mudanças é **aditiva**: novos endpoints, novos parâmetros opcionais, novos campos de resposta, novos valores em campos de texto. Tolere campos e valores desconhecidos — ignore o que não reconhecer. * Cada mudança do contrato aparece no [changelog](/pt/api-reference/changelog) — confira quando algo parecer diferente.