Status HTTP e Tratamento de Erros

Atenção

Enquanto sua aplicação estiver em desenvolvimento, você deve utilizar somente o endpoint Sandbox em https://sandbox.boletocloud.com, isso evitará maiores problemas como bloqueio de chamadas, inconsistência de dados e até o bloqueio total da conta na plataforma.

Uma das vantagens da abordagem REST é a padronização adquirida com o protocolo HTTP, que por sua vez, traz um conjunto de códigos de status definido. Utilizamos desse conjunto de status retornado em cada requisição para indicar situações de sucesso ou falha dos serviços e detalharmos o erro. Caso exista algum erro, o mesmo será retornado no corpo resposta em formatoJSON.

Os códigos de status HTTP seguem as convenções padrão:

Faixa	Descrição
1xx	Informação
2xx	Sucesso
3xx	Redirecionamento
4xx	Erro do cliente
5xx	Erro do servidor

Estrutura da Resposta de Erro

Como dito anteriormente, em caso de falha de um dado serviço, o erro poderá ser detalhado no corpo da mensagem de resposta em formato JSON. Você deve ter notado a presença do JSON na mensagem de erro da seção de autenticação, a mensagem exibida foi:

{
  "erro": {
    "status": 401,
    "tipo": "autenticacao",
    "causas": [
      {
        "codigo": "2CD228EA",
        "mensagem": "Mensagem do token aqui",
        "suporte": "https://developers.boleto.cloud/"
      }
    ]
  }
}

Na API as mensagens de erros são definidas da seguinte forma:

Propriedades do Objeto de Erro

Propriedade	Tipo	Descrição
status	integer	Código de status HTTP
tipo	string	Categoria do erro na perspectiva da API
causas	array	Coleção de causas do erro com soluções

Propriedades do Objeto de Causa

Propriedade	Tipo	Descrição
codigo	string	Código fixo de classificação do erro
mensagem	string	Mensagem descritiva do erro
suporte	string	Link de ajuda ou informações de suporte

Tratamento de Erros

Agora que você já conhece a estrutura de uma mensagem de erro, deve ter percebido que o tratamento é bem simples. Primeiro, categorize o erro pelo status code (status). Depois, detalhe o que aconteceu processando a lista de causas (causas).

Cada causa pode trazer um código (codigo) fixo, que você pode usar para identificar e tratar aquela situação específica dentro do seu sistema.

Tratamento de Erros:

• Primeiro nível: Classifique pelo código HTTP (status)

• Segundo nível: Processe a lista de causas (causas) para detalhes

• Terceiro nível: Utilize o código único (codigo) de cada causa para tratamento específico no sistema

Postman

Use o Postman principalmente para depurar erros através de sua interface amigável para testar vários cenários de parâmetros.

cURL

status_code=$(curl -s -o response.txt -w "%{http_code}" \
  -u "api-key_SUA-API-KEY:token" \
  "https://sandbox.boletocloud.com/api/v1/boletos/1")

if [ $status_code = "200" ]; then
  echo 'Sucesso'
else
  echo "Erro - Status Code: ${status_code}"
  cat response.txt
fi

Java

import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.core.Response;
import org.glassfish.jersey.client.authentication.HttpAuthenticationFeature;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import static javax.ws.rs.core.MediaType.WILDCARD;

public class TratamentoErros {
    public static void main(String[] args) throws Exception {
        Response response = ClientBuilder.newClient()
            .target("https://sandbox.boletocloud.com/api/v1/boletos/1")
            .register(HttpAuthenticationFeature.basic("api-key_SUA-API-KEY", "token"))
            .request(WILDCARD)
            .get();

        if (response.getStatus() == 200) {
            System.out.println("Sucesso!");
        } else {
            JsonNode erro = new ObjectMapper().readTree(response.readEntity(String.class));
            for (JsonNode causa : erro.get("erro").get("causas")) {
                System.out.println(causa.get("codigo").asText() + " - " + causa.get("mensagem").asText());
            }
        }
    }
}

Kotlin

import okhttp3.Credentials
import okhttp3.OkHttpClient
import okhttp3.Request
import com.fasterxml.jackson.module.kotlin.jacksonObjectMapper

fun main() {
    val client = OkHttpClient()
    val credential = Credentials.basic("api-key_SUA-API-KEY", "token")

    val request = Request.Builder()
        .url("https://sandbox.boletocloud.com/api/v1/boletos/1")
        .header("Authorization", credential)
        .build()

    client.newCall(request).execute().use { response ->
        if (response.isSuccessful) {
            println("Sucesso!")
        } else {
            val mapper = jacksonObjectMapper()
            val erro = mapper.readTree(response.body?.string())
            erro["erro"]["causas"].forEach { causa ->
                println("${causa["codigo"].asText()} - ${causa["mensagem"].asText()}")
            }
        }
    }
}

C#

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;

class Program {
    static async Task Main(string[] args) {
        using var client = new HttpClient();
        var credentials = Convert.ToBase64String(Encoding.ASCII.GetBytes("api-key_SUA-API-KEY:token"));
        client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials);

        var response = await client.GetAsync("https://sandbox.boletocloud.com/api/v1/boletos/1");

        if (response.IsSuccessStatusCode) {
            Console.WriteLine("Sucesso!");
        } else {
            var json = await response.Content.ReadAsStringAsync();
            var doc = JsonDocument.Parse(json);
            foreach (var causa in doc.RootElement.GetProperty("erro").GetProperty("causas").EnumerateArray()) {
                Console.WriteLine($"{causa.GetProperty("codigo")} - {causa.GetProperty("mensagem")}");
            }
        }
    }
}

Node

const https = require('https');

const options = {
  hostname: 'sandbox.boletocloud.com',
  path: '/api/v1/boletos/1',
  method: 'GET',
  auth: 'api-key_SUA-API-KEY:token'
};

const req = https.request(options, (res) => {
  let data = '';
  res.on('data', chunk => data += chunk);
  res.on('end', () => {
    if (res.statusCode === 200) {
      console.log('Sucesso!');
    } else {
      const erro = JSON.parse(data);
      erro.erro.causas.forEach(causa => {
        console.log(`${causa.codigo} - ${causa.mensagem}`);
      });
    }
  });
});

req.end();

Go

package main

import (
    "encoding/json"
    "fmt"
    "io"
    "net/http"
)

type Erro struct {
    Erro struct {
        Causas []struct {
            Codigo   string `json:"codigo"`
            Mensagem string `json:"mensagem"`
        } `json:"causas"`
    } `json:"erro"`
}

func main() {
    req, _ := http.NewRequest("GET", "https://sandbox.boletocloud.com/api/v1/boletos/1", nil)
    req.SetBasicAuth("api-key_SUA-API-KEY", "token")

    resp, err := http.DefaultClient.Do(req)
    if err != nil { panic(err) }
    defer resp.Body.Close()

    if resp.StatusCode == 200 {
        fmt.Println("Sucesso!")
    } else {
        body, _ := io.ReadAll(resp.Body)
        var erro Erro
        json.Unmarshal(body, &erro)
        for _, causa := range erro.Erro.Causas {
            fmt.Printf("%s - %s\n", causa.Codigo, causa.Mensagem)
        }
    }
}

PHP

<?php
$url = 'https://sandbox.boletocloud.com/api/v1/boletos/1';
$api_key = 'api-key_SUA-API-KEY';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_USERPWD, "$api_key:token");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($http_code == 200) {
    echo "Sucesso!\n";
} else {
    $erro = json_decode($response, true);
    foreach ($erro['erro']['causas'] as $causa) {
        echo $causa['codigo'] . ' - ' . $causa['mensagem'] . "\n";
    }
}
?>

Python

import requests
from requests.auth import HTTPBasicAuth

response = requests.get(
    'https://sandbox.boletocloud.com/api/v1/boletos/1',
    auth=HTTPBasicAuth('api-key_SUA-API-KEY', 'token')
)

if response.status_code == 200:
    print('Sucesso!')
else:
    erro = response.json()
    for causa in erro['erro']['causas']:
        print(f"{causa['codigo']} - {causa['mensagem']}")

Ruby

require 'net/http'
require 'uri'
require 'json'

uri = URI('https://sandbox.boletocloud.com/api/v1/boletos/1')

Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
  request = Net::HTTP::Get.new(uri)
  request.basic_auth('api-key_SUA-API-KEY', 'token')

  response = http.request(request)
  if response.code == '200'
    puts 'Sucesso!'
  else
    erro = JSON.parse(response.body)
    erro['erro']['causas'].each do |causa|
      puts "#{causa['codigo']} - #{causa['mensagem']}"
    end
  end
end

Clojure

(require '[clj-http.client :as client])

(let [response (client/get
                "https://sandbox.boletocloud.com/api/v1/boletos/1"
                {:basic-auth ["api-key_SUA-API-KEY" "token"]
                 :as :json
                 :throw-exceptions false})]
  (if (= 200 (:status response))
    (println "Sucesso!")
    (doseq [causa (get-in response [:body :erro :causas])]
      (println (:codigo causa) "-" (:mensagem causa)))))

Visão geral >> sobre os exemplos.