Como verificar e tratar erros e códigos de erros comuns no consumo de API's

HTTP Error Codes no Consumo de API's

Quando usamos API's para comunicação entre serviços, os HTTP Error Codes são códigos numéricos que indicam o status de uma requisição. Eles ajudam a entender se a solicitação foi bem-sucedida ou se algo deu errado.

Na tela abaixo, em uma tentativa de consumir a API do Zeev, por exemplo, podemos ver em destaque o código de HTTP Error Code (401).

Junto com o código de erro, o Zeev disponibiliza um documento JSON com detalhes de erro. Esse "documento" traz informações para você entender onde está o problema.

Os principais códigos de erro que podem ocorrer são:

400 Bad Request

Este código indica que o sistema não conseguiu entender a solicitação devido a uma sintaxe ou regra de negócio inválida. Isso pode ocorrer por diversos motivos, tais como:

• Seu JSON está inválido. Alguns softwares na internet podem ajudar a validar se o JSON está correto, como o https://jsonlint.com/

• Você está tentando usar operadores oData não permitidos nessa API;

• Você não está preenchendo todos as propriedades obrigatórias do JSON da solicitação. Por exemplo, pode haver uma propriedade chamada flowId , que pela documentação é obrigatório, e você não está enviando ela;

• Você não está preenchendo corretamente, com dados válidos, todos as propriedades o JSON da solicitação. Por exemplo, pode haver uma propriedade que espera uma data, e você está enviando uma string;

Geralmente, ao ler o JSON de erro de retorno da API, você terá informações necessárias para entender onde pode estar o problema.

401 Unauthorized

Esse código ocorre quando existe um problema de autenticação com o token de autenticação. Por exemplo:

• O token é inválido, não existe, ou não foi copiado corretamente;

• O token não é válido nesse ambiente;

• O token refere-se a um usuário que está inativo ou bloqueado;

403 Forbidden

Esse código ocorre quando existe um problema de permissão com o token de autenticação. O token é válido, foi possível fazer o login na API, porém esse token não tem permissão de realizar essa operação. Por exemplo:

• O usuário dono desse token não faz parte de um grupo de manutenção que tenha o acesso ao recurso ou operação que você quer realizar;

• O usuário dono desse token não tem permissão de iniciar o aplicativo / solicitação que você deseja;

• O usuário dono desse token não é dono / responsável pela tarefa que você quer finalizar;

Reveja as permissões associadas ao usuário dono do token.

404 Not Found

Esse código ocorre em dois cenários.

No primeiro cenário, você está chamando uma URL do Zeev que não existe. Verifique a URL da sua chamada de API.

O segundo cenário ocorre quando você quer realizar uma operação em um registro que não existe. Por exemplo:

• Você está tentando iniciar uma solicitação que não existe;

• Você está tentando finalizar uma tarefa que não existe ou já foi finalizada;

• Você está tentando atualizar os dados de um usuário que não existe;

Verifique o ID da operação que você quer realizar.

429 Too Many Requests

Esse código de erro ocorre quando você extrapola o limite máximo de solicitações por um determinado período de tempo.

Verifique mais informações aqui.

500 Internal Server Error

Esse código ocorre quando ocorreu um problema no produto. Entre em contato com nosso suporte técnico, enviando o máximo de informações possíveis, tais como:

• Endereço da API que você está solicitando;

• Token de autenticação;

• Corpo JSON

• Mensagem de erro completa;

Como verificar se erros ocorreram em código

Uma das maneiras mais simples de verificar se ocorreu um erro é testar se o documento JSON retornado pela API é um documento de erro. Para isso, simplesmente verifique se a propriedade raiz chama-se error.

Veja exemplo abaixo.

Node.js

async function exampleWithError() {

    const options = {
        method: 'GET',
        headers: {
            'Content-Type': 'application/json',
            Authorization: 'Bearer TOKEN_DO_USUARIO'
        }
    };

    const response = await fetch('http://endereco.do.zeev.it/api/2/requests', options)
    const data = await response.json();

    //verifica se ocorreu um erro
    if(data==null || data.error) {
        console.log("Ocorreu um erro ao chamar a API:", data?.error);
        return;
    }

    //prossegue sem erros
    //...

}

exampleWithError();