Erros comuns Introdução Nós usamos HTTP codes para diferenciar as requisições bem sucedidas de requisições que contenham erros. Sempre serão informados o tipo, mensagem e descrição do erro. Erros 4xx apontam inconsistências nos dados enviados.
Erros 5xx apontam falhas no nosso serviço. A listagem abaixo exemplifica códigos de erros e mensagens que podem ser encontrados durante o uso da API. VALIDATION_ERROR Ocorre quando houve erros na validação dos campos enviados pela requisição. HTTP Code: 400 MISSING_REQUIRED_FIELD_ERROR Ocorre quando campos obrigatórios não foram enviados. HTTP Code: 400 UNKNOWN_ERROR Ocorre quando uma operação não pode ser concluida. HTTP Code: 400 UNAUTHORIZED Ocorre quando a chave de acesso informada não está válida. HTTP Code: 401 FORBIDDEN Ocorre quando o token enviado não possui permissão para operar nos escopos requisitados. HTTP Code: 403 RESOURCE_NOT_FOUND Ocorre quando a URN ou URI informada não existe, ou quando o recurso solicitado não foi encontrado no sistema. HTTP Code: 404 TOO_MANY_REQUESTS Ocorre quando o total de requisições feitas atingiu o seu limite. Conforme a página limites. HTTP Code: 429 SERVER_ERROR Ocorre quando algum processo interno no servidor da nossa aplicação possui alguma falha. HTTP Code: 500 Exceções Obtenção do authorization code Neste tópico são citados alguns erros que poderão ocorrer na etapa de requisição do authorization_code. De modo geral, os erros serão retornados para a URL de redirecionamento informada no cadastro do aplicativo com a estrutura de parâmetros demonstrada na tabela abaixo. Aplicativo não autorizado Caso o usuário não autorize o acesso aos escopos solicitados pelo aplicativo, o erro será retornado através da URL de redirecionamento do aplicativo. Aplicativo inativado Caso o aplicativo esteja inativado (conforme seção situação do aplicativo) você não será capaz de realizar nenhum tipo de requisição. Um erro, como o do exemplo abaixo, será retornado através da URL de redirecionamento do aplicativo. Usuário não autorizado Exceções causadas por usuários não autorizados poderão ser redirecionadas para o callback do aplicativo, veja o exemplo abaixo. Isso poderá ocorrer especificamente quando for requisitado um novo authorization_code para um usuário que já concedeu autorização previamente ao aplicativo. Porém, este usuário perdeu alguns privilégios durante este tempo (deixou de ter permissão para algum escopo solicitado na autorização) ou a conta passou para a situação inadimplente. Obtenção da URL de redirecionamento Ocorre geralmente quando o client_id da requisição for inválido. Obtenção dos tokens de acesso O formato dos erros retornados durante esta requisição seguem o modelo adotado pela API v3 do Bling, um objeto JSON contendo as informações sobre o erro no body da resposta HTTP. Este tópico não é uma lista completa de todos os erros que poderão ocorrer durante a requisição dos tokens de acesso, porém, a leitura deste manual poderá ajudar na interpretação da maioria dos erros. Sintaxe Independente do grant type (authorization_code ou refresh_token) utilizado, os erros mais comuns durante esta etapa são causados por problemas na sintaxe da requisição. Os exemplos mais comuns são: ausência parâmetros obrigatórios no body ou as credenciais no cabeçalho, grant type inválido, credenciais inválidas, code inexistente ou expirado. Veja abaixo os objetos JSON retornados nas requisições com erro nas credenciais do aplicativo e authorization_code expirado. Authorization code já utilizado É permitido que cada authorization_code seja utilizado apenas uma vez. Caso um authorization_code válido (não expirado) for utilizado em uma segunda requisição para obtenção dos tokens de acesso, esta requisição não será válida e por medidas de segurança o usuário vinculado ao code terá o seu acesso revogado. Segue abaixo o JSON retornado neste caso. Empresa inativa Assim como não é permitida a geração de um novo authorization_code aos usuários vinculados a empresas com situação diferente de ativa, não será permitida a obtenção de novos tokens de acesso com uso do refresh token. Nestes casos, o JSON abaixo será inserido no retorno. Obter recurso do usuário O formato dos erros retornados durante esta requisição seguem o modelo adotado pela API v3 do Bling, um objeto JSON contendo as informações sobre o erro no body da resposta HTTP. Este tópico detalha os erros causados durante a validação do access_token utilizado na autenticação OAuth, não serão detalhados os demais erros que poderão ocorrer na requisição do recurso, para isso consulte o tópico sobre erros da API v3. Problemas de sintaxe Qualquer problema com relação à sintaxe da inserção do access token na requisição. Token expirou Access token expirado. Utilize o refresh token para gerar uma nova chave a este usuário, veja o tópico refresh token para mais informações. Token não autorizado Caso o recurso requisitado não tenha sido autorizado pelo usuário, ou seja, o access_token não possui permissão para acessar o escopo referente a este recurso.