O que é um catálogo de erros e como mapear códigos de erro para novas tentativas?

Uma solicitação com falha pode precisar de um atraso, de um campo corrigido ou de uma credencial diferente. A resposta de erro da Bird fornece campos que seu handler pode usar para escolher essa ação.

Quais campos de erro devo usar?

Use type para tratamento amplo e code para uma recuperação específica. Bird coloca esses campos dentro de um objeto de nível superior error.

O type agrupa falhas como validação, autenticação e limitação de requisições. O code identifica a falha específica, como E01001 para validação de campo.

Bird nunca renomeia nem reutiliza um código. Códigos aposentados permanecem reservados, então um match de código existente mantém seu significado.

Exiba ou registre message, mas não compare seu texto. A redação pode mudar sem alterar a falha que seu handler precisa tratar.

O name torna os logs legíveis. O doc_url aponta para a documentação do código. Registre code, name e request_id juntos quando uma operação falhar.

Quais falhas devo tentar novamente?

Tente novamente em falhas temporárias com uma política limitada. Corrija problemas de entrada e credencial antes de tentar de novo. Verifique o código específico quando um mesmo status pode exigir ações diferentes.

Mantenha a mesma chave de idempotência ao tentar novamente a mesma escrita. Um timeout ou falha de servidor não prova que a operação original não fez nada.

Pare quando o orçamento de novas tentativas se esgotar e registre o erro final. Repetir indefinidamente uma solicitação inalterada pode esconder uma falha que precisa de intervenção.

Como trato erros de validação de campo?

Leia o array details em E01001 ValidationError e associe cada entrada ao seu param. Exiba o message dessa entrada ao lado do campo afetado.

Não faça parsing dessas mensagens para identificar o campo ou a falha. A redação pode mudar, assim como a mensagem de nível superior.

Uma solicitação malformada pode retornar E01002 InvalidRequest. Use a recuperação documentada em vez de assumir que toda falha de entrada contém detalhes em nível de campo.

A resposta pode me dizer como recuperar?

Alguns erros incluem remediation, um próximo passo legível, ou next, uma lista ordenada de operações a tentar.

Exiba a remediação quando ela ajudar a pessoa a corrigir o problema. Por exemplo, uma falha de autorização pode exigir uma credencial com um escopo adicional.

Um handler automatizado pode usar next para escolher uma operação de recuperação. Ele ainda precisa das entradas e permissões dessa operação antes de executá-la.

Um vendor_code identifica uma falha downstream, como uma resposta SMTP ou recusa de pagamento. Consulte o código desse provedor quando a recuperação depender dele.

O que deve acontecer com um código desconhecido?

Mantenha um branch padrão que registre a falha sem quebrar ou tentar novamente indefinidamente. Novos códigos e tipos podem aparecer conforme o API cresce.

Aplique uma política de nova tentativa baseada em status quando apropriado. Caso contrário, pare e registre o código com seu request ID para investigação.

O guia de erros documenta a resposta de erro. A referência de erros lista códigos individuais e suas orientações de recuperação.