> ## Documentation Index > Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt > Use this file to discover all available pages before exploring further. # Tratar erros > Entenda as respostas de erro da YCloud e repita requisições com segurança. ## O que é A YCloud usa códigos de status HTTP e um corpo de erro estruturado para que sua aplicação possa decidir se deve corrigir, rejeitar ou repetir uma requisição. ## Resposta Uma requisição com falha retorna um objeto `error`. ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "error": { "status": 404, "code": "NOT_FOUND", "message": "The requested resource does not exist.", "requestId": "req_1KjtKI80IKoaJNa6n6p" } } ``` ## Campos de erro | Campo | Descrição | | - | - | | `status` | Código de status HTTP obrigatório retornado pela API. | | `code` | Código de erro legível por máquina obrigatório da YCloud. | | `message` | Explicação voltada para desenvolvedores. Não mostre diretamente aos usuários finais. | | `target` | Campo da requisição ou recurso associado ao erro, quando disponível. | | `docUrl` | Link para mais informações, quando disponível. | | `requestId` | Identificador da requisição, também retornado no cabeçalho `YCloud-Request-ID`, para rastreamento da requisição com o suporte da YCloud. | | `whatsappApiError` | Detalhes originais do erro do WhatsApp, quando uma requisição direta da API do WhatsApp atinge a Meta e falha. | ## Códigos de erro Use `error.code` para distinguir falhas que compartilham um mesmo status HTTP. Este catálogo lista os códigos de erro da API da YCloud; um endpoint pode documentar erros adicionais. | Código | Status HTTP | Significado e ação | | - | - | - | | `ACCOUNT_LIMITED` | `403` | Uma restrição de conta impede a ação. Por exemplo, uma conta de teste só pode enviar para números pré-verificados. Verifique as restrições de conta aplicáveis. | | `ACCOUNT_RATE_LIMITED` | `429` | A cota da conta foi esgotada. Pause as requisições que compartilham a cota e respeite `Retry-After`. | | `ACCOUNT_UNAVAILABLE` | `403` | A conta está indisponível. Entre em contato com o suporte da YCloud. | | `ALREADY_EXISTS` | `409` | O recurso já existe. Verifique os recursos existentes e os parâmetros da requisição antes de criar outro. | | `BAD_REQUEST` | `400` | Os parâmetros da requisição são inválidos. Corrija a requisição usando os detalhes do erro. | | `BALANCE_INSUFFICIENT` | `403` | A conta possui saldo insuficiente. Recarregue antes de tentar novamente. | | `CONTENT_PROHIBITED` | `403` | O conteúdo viola os termos de serviço. Corrija ou remova o conteúdo proibido. | | `CONTENT_TOO_LARGE` | `413` | O conteúdo da requisição é muito grande. Reduza o seu tamanho. | | `EMAIL_DOMAIN_UNVERIFIED` | `403` | O domínio de e-mail não está verificado. Conclua a verificação e aguarde o tempo necessário para que ela entre em vigor. | | `FORBIDDEN` | `403` | Você não pode acessar o recurso. Verifique a propriedade dele e as permissões da sua conta. | | `INTERNAL_SERVER_ERROR` | `500` | A YCloud encontrou um erro no servidor. Repita falhas temporárias com recuo delimitado (bounded backoff), sujeito às regras de repetição da operação. | | `MESSAGING_REGION_UNSUPPORTED` | `400` | O envio de mensagens não é suportado na região solicitada. Verifique o destino. | | `NOT_FOUND` | `404` | O recurso não existe. Verifique o ID dele e o caminho do endpoint. | | `PARAM_INVALID` | `400` | O valor de um parâmetro é inválido. Corrija o campo identificado nos detalhes do erro. | | `PARAM_INVALID_LENGTH` | `400` | Um parâmetro está fora do comprimento permitido. Verifique as restrições do campo. | | `PARAM_MISSING` | `400` | Um parâmetro obrigatório está ausente. Inclua-o na requisição. | | `PARAM_NOT_MATCH` | `400` | Dois ou mais parâmetros são inconsistentes. Verifique a relação obrigatória entre eles. | | `RECIPIENT_IN_BLOCK_LIST` | `403` | O destinatário está bloqueado. Verifique a lista de bloqueio da conta antes de enviar. | | `RECIPIENT_UNSUBSCRIBED` | `403` | O destinatário cancelou a inscrição. Respeite o opt-out e verifique seus registros de cancelamento de inscrição. | | `SENDER_ID_UNAVAILABLE` | `403` | O Sender ID de SMS não está registrado ou ainda está em análise. Verifique o status de registro dele. | | `SENDER_RATE_LIMITED` | `429` | A cota do remetente foi esgotada. Desacelere as requisições que usam esse remetente e respeite `Retry-After`. | | `SERVICE_UNAVAILABLE` | `503` | O serviço está temporariamente indisponível ou sobrecarregado. Tente novamente mais tarde quando for seguro para a operação. | | `SMS_SIGNATURE_UNAVAILABLE` | `403` | A assinatura para SMS na China Continental está indisponível. Verifique a assinatura de SMS. | | `TOO_MANY_REQUESTS` | `429` | As requisições chegaram rápido demais. Respeite o `Retry-After` e reduza o tráfego com backoff e jitter. | | `UNAUTHORIZED` | `401` | Falha na autenticação. Verifique a chave de API em `X-API-Key`. | | `WHATSAPP_PHONE_NUMBER_UNAVAILABLE` | `403` | O número de telefone do WhatsApp está indisponível. Verifique o número remetente. | | `WHATSAPP_TEMPLATE_UNAVAILABLE` | `403` | O modelo do WhatsApp está ausente ou não foi aprovado. Verifique seu nome e status. | | `WHATSAPP_WABA_UNAVAILABLE` | `403` | A conta do WhatsApp Business está indisponível. Verifique o ID da WABA utilizado pela requisição. | | `WHATSAPP_TEMPLATE_UNEDITABLE` | `403` | O modelo não pode ser editado em seu status atual. A edição requer `APPROVED`, `REJECTED` ou `PAUSED`. | Para cotas de conta e remetente, consulte [Limites de taxa](/pt/api-reference/guides/api-fundamentals/rate-limits). Erros da Meta também podem aparecer em `error.whatsappApiError` depois que uma requisição atinge o WhatsApp. Preserve esses detalhes juntamente com o código de erro da YCloud. ## Como lidar com a resposta | Status | Ação recomendada | | - | - | | `400` | Corrija os parâmetros ou o corpo da requisição. | | `401` | Verifique a chave de API. Não tente novamente com as mesmas credenciais sem alteração. | | `403` | Use `error.code` para verificar a restrição de conta, saldo, destinatário ou recurso. Corrija a causa antes de tentar novamente. | | `404` | Verifique o ID do recurso e o caminho do endpoint. | | `429` | Respeite o `Retry-After`, reduza o tráfego e use backoff limitado. | | `5xx` | Tente novamente falhas temporárias com backoff exponencial e jitter. | ## Correlação de requisições Registre o endpoint, o método HTTP, o status da resposta, o `requestId` da YCloud e o seu próprio ID de correlação. Remova chaves de API e dados pessoais. Isso fornece evidências suficientes para investigar uma falha sem expor segredos. ## Tentar novamente com segurança Tente novamente requisições somente leitura quando a falha for temporária. Tenha cuidado com envios de mensagens e outras operações de criação. Um `POST` repetido pode criar um segundo recurso ou enviar uma mensagem duplicada. Quando compatível com o schema da requisição, defina `externalId` para um valor exclusivo do seu sistema. Armazene o ID de resposta da YCloud após uma requisição bem-sucedida. Inclua o `requestId`, endpoint, status HTTP e horário da falha ao entrar em contato com o [suporte da YCloud](mailto:service@ycloud.com). Remova as chaves de API e dados pessoais primeiro. ## Lista de verificação de implementação * Analise erros por `code`, e não correspondendo ao texto de `message`. * Defina timeouts em todas as requisições de saída. * Tente novamente apenas em falhas temporárias. * Adicione backoff exponencial, jitter e um limite máximo de tentativas. * Evite efeitos duplicados de `POST` com seu próprio identificador estável quando a requisição for compatível com um. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.