6 erros de API que ocorrem com frequência e como evitá-los

As APIs são uma parte cada vez mais importante da economia do século 21 e de nossas vidas cotidianas. Grandes empresas como Stripe e Amazon foram construídas em excelentes plataformas de desenvolvimento. Até mesmo ferramentas “analógicas”, como sistemas telefônicos de escritório, estão ficando expostas a APIs. Produtos VoIP cada vez mais avançados integram sistemas de telefonia para pequenas empresas com software como o Google Workspace. Isso abre novas experiências poderosas para funcionários e clientes. Mas as APIs não estão acima dos erros. Se você é um desenvolvedor de projetos amador ou um investidor de um milhão de dólares Produto baseado em SaaS usuário, você descobrirá que falhas são inevitáveis.

O que é um erro/falha de API?

An Erro de API ocorre quando um servidor não consegue localizar o recurso solicitado do provedor de API. Nesses casos, uma mensagem de erro numérica é retornada para ajudar a identificar o erro específico. As causas comuns de erros de API incluem problemas no endpoint, parâmetros incorretos ou problemas com a chave de API durante a chamada de solicitação. A resolução desses erros é crucial para uma comunicação perfeita entre aplicativos e para garantir a recuperação bem-sucedida de dados do provedor de API.

6 erros comuns de API

Alguns erros comuns de API são:

• Erros HTTP/HTTPS.
• Erros de API inúteis.
• Misturas de métodos.
• Cabeçalhos Content-Type/Accept ausentes.
• Erros de autorização.
• Erros de formatação de dados.

1. Erros HTTP/HTTPS

Um dos erros de API mais comuns ocorre quando há confusão entre os protocolos http:// e https:// em URLs.

Para os desenvolvedores, o problema é que algumas APIs suportam apenas o protocolo HTTP, enquanto outras são compatíveis com HTTPS. Alguns oferecem suporte a diferentes padrões em diferentes endpoints no mesmo produto centrado no cliente.

Isso pode ficar ainda mais confuso quando os desenvolvedores estão unindo várias APIs. Se eles são desenvolvedores internos que criam soluções “faça você mesmo” para comunicações de negócios assíncronas com equipes remotas. Os desenvolvedores precisam gastar tempo localizando o endpoint que está causando o problema e, em seguida, criar uma solução alternativa para fazer com que as duas APIs restantes conversem entre si.

Se você é um Provedor de API, você pode evitar esse erro implementando estratégias HTTPS específicas. Por exemplo, você pode fazer com que sua API redirecione automaticamente solicitações HTTP para solicitações HTTPS à medida que elas chegam.

2. Mensagens de erro de API inúteis

Para seus usuários, a qualidade de suas mensagens de erro pode ser a diferença entre um breve soluço e uma hora gasta arrancando os cabelos, o que ajuda a reduzindo a rotatividade de clientes.

O HTTP fornece mais de 70 códigos de status http, mas, no mínimo, você só precisa implementar os códigos mais comuns com os quais os desenvolvedores estão acostumados a trabalhar. Exemplos desses incluem:

200 OK

Tudo certo! Apenas tome cuidado para fornecer este código de status apenas se tudo realmente is OK. A Graph API do Facebook é conhecida por fornecer um código 200 sempre que retorna com sucesso alguma saída, mesmo que essa saída contenha um código de erro.

400 Bad Request

Isso quase sempre ocorre devido a um erro de digitação na entrada do usuário. Mas isso não significa que você está fora do gancho! Certifique-se de que sua mensagem de erro forneça alguns detalhes sobre a entrada defeituosa para que o usuário possa corrigi-la rapidamente.

401 não autorizado

Esse status significa que a entrada está correta, mas a solicitação dos usuários não contém um código de autorização. Não confundir com…

Proibida 403

Isso significa que o código de autorização é reconhecido como válido, mas o usuário não tem permissão. Por exemplo, um usuário pode estar tentando acessar algo disponível apenas para os administradores, uma preocupação de segurança crescente com a equipe remota.

404 não encontrado

A solicitação do usuário é válida, mas o endpoint ou recurso que ele está solicitando não existe. Isso pode ocorrer porque o arquivo já foi excluído, mas certifique-se de que isso não seja causado por um erro HTTP/HTTPS.

429 Pedidos demais

Isso ocorre quando o mesmo usuário está tentando chamar a API muitas vezes em rápida sucessão. Após uma série de ataques DDoS de alto nível na última década, os serviços da Web estão de olho em quem está acessando seu servidor e com que frequência.

Essa limitação de taxa é semelhante ao que você encontraria em qualquer domínio ou em outros sites grandes. Provedores de hospedagem na Web como Cloudflare lidam com proteção DDoS para domínios hospedados em seus servidores. Para APIs, essas proteções precisam ser integradas.

Erros de API 5xx

Os códigos de status que começam com 5 são todos erros do servidor, potencialmente do seu lado. Se for esse o caso, certifique-se de que suas mensagens de erro forneçam alguma ajuda ou segurança ao usuário. Isso pode ser informações de contato ou uma página com informações de tempo de atividade/inatividade ao vivo.

Os provedores de API podem evitar mensagens de erro ruins com apenas um pouco de adaptação e tratamento de erros. Vá além do código de erro e use mensagens claras e sucintas que levem à documentação.

Os provedores de software devem ter criado um perfil de consumidor-alvo dos desenvolvedores que usarão sua API. As mensagens de erro podem e devem ser adaptadas aos tipos de tarefas digitais que tentarão realizar.

Dê uma olhada nesta mensagem de erro do Twilio, cuja API permite que os desenvolvedores façam uma chamada VoIP.

""

{

“código”: 21211,

“message”: “O número 'Para' 5551234567 não é um número de telefone válido.”,

“mais_info”: “https://www.twilio.com/docs/errors/21211”,

“estado”: ​​400

}

""

Além do status padrão 400, há um código de erro personalizado “21211” na parte superior. A mensagem ainda se refere ao número de telefone virtual específico que está causando o problema. Ele encaminha o usuário para a página em sua documentação onde eles discutem o problema 21211.

Mensagens de erro ruins podem ser um grande obstáculo para os desenvolvedores que tentam integrar uma API em sua empresa orientada a produtos. Um processo de integração fácil é fundamental para o sucesso de uma API. Uma das primeiras coisas que muitas pessoas ouvem sobre o Stripe é como é fácil colar apenas algumas linhas de código e fazer os pagamentos se moverem. Boas mensagens de erro, portanto, não são apenas importantes para a funcionalidade, elas também são um ótimo recurso de marketing para sua API.

3. Misturas de Métodos

As APIs e seus usuários podem encontrar erros quando misturam seus métodos de solicitação. Se o usuário enviar uma solicitação POST que é redirecionada e retornada como uma solicitação GET, isso pode causar um erro frustrante que não é culpa dele.

Outra causa de erros de método é a documentação pouco clara. Isso pode acontecer quando uma seção de sua documentação não explica quais métodos são necessários ou usa o verbo totalmente errado. (Cuidado com o uso da palavra “get” e GET de forma intercambiável. Certifique-se de que a formatação de seus documentos esteja clara e salve um e-mail de suporte ao cliente.)

Desenvolva uma API REST robusta e segura em minutos

Ver demonstração

4. Faltam cabeçalhos Content-Type/Accept

A maioria das chamadas de API tem pelo menos dois dados de cabeçalho: Content-Type e Accept. Esses cabeçalhos ajudam duas partes – como duas APIs – a negociar que tipo de dados está sendo enviado e quais tipos serão aceitos em troca. Como qualquer negociação, estas podem falhar.

Algumas APIs aceitarão solicitações que não tenham esses cabeçalhos se não houver motivo para serem tão rigorosas. Cada linha de código introduz possíveis erros no software, portanto, os provedores de PBX em nuvem geralmente não especificam um requisito de cabeçalho se não for necessário. Mas em APIs comerciais com preocupações de segurança, os desenvolvedores solicitarão cabeçalhos Content-Type e Accept específicos. Isso permite que eles controlem rigidamente o que é permitido em seu sistema e o que é permitido passar.

Content-Type informa à API o formato da data que você está enviando e Accept informa à API o que enviar de volta. APIs podem exigir apenas que você tenha algo nos cabeçalhos, alguns aceitarão tipos específicos e rejeitarão outros.

Essas informações devem ser especificadas na documentação quando isso não for um risco de segurança, mas certas ferramentas de desenvolvedor podem enganar os usuários. Considere o curl, que inclui automaticamente o cabeçalho Accept padrão nas solicitações. Os provedores de API podem antecipar essas peculiaridades de ferramentas, modificando a solicitação ou enviando uma mensagem de erro específica.

5. Erros de autorização

Este é um erro de API comum e muitas vezes muito simples. As APIs que usam o protocolo de segurança OAuth 2 exigem uma parte extra de dados de cabeçalho para processar solicitações. Este é o cabeçalho de “autorização”, contendo a chave privada necessária para que a API processe a solicitação.

É um erro comum enviar um cabeçalho de “autenticação”. Isso ocorre porque os desenvolvedores e a documentação geralmente falam sobre autenticação e autorização de forma intercambiável. Mas mesmo que o cabeçalho esteja corretamente rotulado como “autorização”, erros de formatação confusos podem enganar as pessoas.

Certifique-se de que as solicitações da API OAuth 2 estejam formatadas assim, com o sinalizador "Bearer" antes da chave privada:

""

Autorização: Portador {your_api_key_here}

""

Os pares de nome de usuário e senha devem ser formatados como “username:password”. Mas mesmo que a solicitação da API não exija uma senha, os usuários podem ter que acrescentar dois pontos no final. Os próprios provedores de API podem anexar os dois pontos ou deixar claro na documentação exatamente qual é a formatação.

6. Erros de formatação de dados

Mesmo que o usuário esteja fazendo tudo certo, APIs ainda pode cuspir dados no formato errado. Se a API fornecer aos usuários seus dados em HTML em vez do JSON que eles pensaram ter solicitado, isso poderá causar uma falha total. Pior ainda, seu desenvolvimento de software pode aceitar alegremente os dados e processá-los de uma maneira que não é esperada.

Se o desenvolvedor estiver tentando juntar serviços para medir a taxa de conversão de sites de comércio eletrônico, a equipe de marketing não verá o código. Eles podem passar dias analisando dados defeituosos antes que alguém perceba que algo não está certo.

Mencionamos métodos de solicitação padronizados para GET devido a um redirecionamento. Mas com mais frequência esse erro ocorre quando o usuário não especificou o cabeçalho Accept corretamente, se for o caso. Isso pode dar aos provedores um motivo para serem mais rigorosos sobre quais tipos de conteúdo eles aceitam, mesmo que não seja um risco de segurança.

Os provedores de API também devem verificar os tipos de respostas que podem receber como padrão ou com erro. Se sua API não tiver motivos para processar HTML, você deve rejeitar esse tipo de conteúdo. Isso evita problemas que você pode encontrar com ferramentas comuns. Por exemplo, sempre que o Nginx recebe um tempo limite de solicitação, ele pode fornecer um erro de HTML que sua API não tem ideia de como processar.

Prevenção de erros explicada

Prevenir muitos desses erros comuns se resume a testes completos. Também é uma boa ideia controlar rigidamente quais dados sua API aceitará quando estiver disponível. Além disso, os provedores de API devem valorizar a excelente documentação da API e as mensagens de erro.

Isso ajudará os usuários a descobrir os problemas por si mesmos, mas se se trata de um software para atendimento ao cliente, ele ajudará você a resolver o problema mais rapidamente. Depois de identificar essa falha, é hora de ver se você pode melhorar seus documentos ou até mesmo abstrair todo o problema para que não aconteça novamente.

Saiba mais sobre gerenciamento de API de ponta a ponta rápido e simples

download do whitepaper