Tratar erros

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.

{
  "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. 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. 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.

Primeiros passos

Guias

Endpoints

Webhooks

O que é

Resposta

Campos de erro

Códigos de erro

Como lidar com a resposta

Correlação de requisições

Tentar novamente com segurança

Lista de verificação de implementação

​O que é

​Resposta

​Campos de erro

​Códigos de erro

​Como lidar com a resposta

​Correlação de requisições

​Tentar novamente com segurança

​Lista de verificação de implementação

O que é

Resposta

Campos de erro

Códigos de erro

Como lidar com a resposta

Correlação de requisições

Tentar novamente com segurança

Lista de verificação de implementação