REFERÊNCIA DA API

Erros e limites

Como a API responde quando algo dá errado, quantas chamadas cada plano permite e o que fazer em cada caso.

Objeto de erro

Toda resposta de erro tem success: false e um objeto error com code (estável, para tratar no código) e message (texto para leitura). Erros de validação trazem também details, com o parâmetro em loc.

Exemplos de erro

{
  "success": false,
  "error": {
    "code": "http_error",
    "message": "Invalid API key"
  },
  "meta": {
    "request_id": "ecc080da-f8a8-4727-9395-34930a1c3f75"
  }
}

Códigos HTTP

Código	Quando acontece	O que fazer
`200`	Sucesso.	Leia o resultado em data.
`202`	Série nova sendo preparada.	Repita depois de retry_after segundos.
`400`	Combinação de parâmetros inválida.	Revise a chamada pela mensagem.
`401`	Chave ausente, inválida ou revogada.	Confira o cabeçalho X-API-Key.
`403`	E-mail não confirmado ou recurso fora do seu plano.	Confirme o e-mail ou veja os planos.
`404`	Série, ativo ou recurso não encontrado.	Busque o identificador correto.
`422`	Parâmetro faltando, com tipo errado ou dado indisponível para o período.	Veja details.loc e a mensagem.
`429`	Limite por minuto ou cota do mês excedidos.	Espere e tente de novo, ou mude de plano.
`501`	Formato pedido ainda não disponível.	Use json, csv ou xlsx.
`5xx`	Falha temporária do serviço.	Tente de novo com espera.

Série em preparo (202)

Ao pedir pela primeira vez uma série do Banco Central que ainda não está no catálogo, a API cadastra a série e começa a buscar o histórico. A resposta é 202 com o tempo sugerido para tentar de novo:

Resposta

{
  "status": "discovering",
  "series_id": "5c1d7e0a-3b9f-4d2e-8a61-0f4b7c9e2d13",
  "retry_after": 30
}

Espere retry_after segundos e repita a mesma chamada. Em geral o histórico completo fica pronto em menos de um minuto.

Limites por plano

Há dois limites por conta, somados entre todas as chaves: por minuto (picos) e por mês (cota).

Plano	Por minuto	Por mês
Free	60	5.000
Individual	200	20.000
Pro	600	75.000
Empresas	sob consulta

Ao passar do limite por minuto, a resposta é 429 com code: "rate_limit_exceeded"; ao esgotar a cota do mês, code: "monthly_quota_exceeded". Os dois trazem limit, used e window. Acompanhe o consumo em Uso da API ou com o comando uso no terminal.

Boas práticas

Tente de novo com espera em 429 e 5xx: 1 s, 2 s, 4 s… com um teto. Não repita 4xx de validação sem mudar a chamada.
Peça só o necessário: date_from e limit reduzem o volume e o tempo de resposta.
Guarde o que já baixou: séries diárias mudam uma vez por dia; consulte só o trecho novo.
Registre o meta.request_id das chamadas com erro e envie ao suporte.