Erros e retries

Todo erro volta no mesmo formato:

{
  "error": "invalid_request",
  "code": "invalid_request",
  "message": "invalid request body",
  "status": 422
}

error e code trazem o mesmo valor. Programe contra o code, nunca contra a message, que é livre e pode mudar. Erros de validação invalid_request podem trazer um campo details com os erros por campo:

{
  "error": "invalid_request",
  "code": "invalid_request",
  "message": "invalid request body",
  "status": 422,
  "details": {
    "fieldErrors": {
      "cpf": ["CPF is invalid (mod11 checksum failed)"]
    }
  }
}

Autenticação e autorização

Código	HTTP	Quando acontece
`unauthorized`	401	Qualquer falha antes da autorização: credencial ausente ou inválida, IP fora da allowlist, timestamp fora da janela, assinatura errada ou requisição repetida. Código único e opaco, por segurança. Ver Autenticação.
`insufficient_scope`	403	A credencial é válida, mas não tem o escopo que a rota exige.
`feature_not_available`	403	O recurso não está habilitado para a sua credencial.

Conta e vínculo

Código	HTTP	Quando acontece
`account_not_found`	404	A conta não existe, não é sua, está suspensa, o vínculo foi revogado ou o cadastro ainda não foi aprovado. Resposta idêntica em todos os casos, e nenhuma chamada ao provedor é feita.
`account_not_bindable`	422	A conta está aprovada, mas não tem titular associado. Situação anormal: abra um chamado.
`transaction_not_found`	404	A transação informada não existe no extrato da conta.

404 não significa só “conta errada”. Saldo e status de transação passam por uma verificação que exige o cadastro aprovado. Uma conta recém-aberta, ainda em under_review, responde 404 account_not_found em GET /v1/accounts/{accountId}/balance e em /transactions/{transactionId}, mesmo sendo sua.Antes de concluir que perdeu o vínculo, consulte GET /v1/accounts/{accountId}/status: essa rota funciona desde a criação. Ver Contas gerenciadas.

Abertura de conta

Código	HTTP	Quando acontece
`cpf_already_registered`	409	Já existe conta para esse CPF. É também o que você recebe ao repetir uma abertura depois que a janela de idempotência de 24 h fechou.
`cnpj_already_registered`	409	Já existe conta para esse CNPJ, na mesma lógica acima.
`phone_already_registered`	409	Já existe conta para esse telefone. Vale para PF e PJ.
`account_already_registered`	409	O CPF, CNPJ ou e-mail pertence a uma conta que você não gerencia. Uma conta que já é sua não cai aqui.

Se você recebeu cpf_already_registered numa retentativa e não guardou o accountId, recupere-o em GET /v1/accounts. A conta foi criada uma vez só; a janela de idempotência apenas parou de repetir a resposta original. Ver Idempotência.

Validação e idempotência

Código	HTTP	Quando acontece
`invalid_request`	422	Corpo, parâmetro ou identificador inválido. Campos desconhecidos são rejeitados.
`missing_idempotency_key`	422	Faltou o header `Idempotency-Key` em uma operação que altera estado.
`idempotency_conflict`	409	A mesma chave foi usada com um corpo diferente.
`request_in_progress`	409	A primeira requisição com essa chave ainda está sendo processada.
`request_body_too_large`	413	O corpo passou de 1 MB.

Dinheiro

Estes códigos aparecem quando as rotas de pagamento estiverem liberadas para a sua credencial.

Código	HTTP	Quando acontece
`activation_pending`	402	A conta ainda não concluiu a ativação. Nenhuma chamada ao provedor é feita.
`account_not_approved`	422	A conta existe, mas não concluiu a aprovação de KYC.
`insufficient_balance`	422	A conta não tem o valor disponível.
`per_tx_limit_exceeded`	422	O valor passou do teto por transação acordado.
`cashout_limit_not_configured`	422	A credencial não tem teto por transação configurado. A regra falha fechada: sem teto, nada sai.
`daily_cashout_limit_not_enforced`	422	Existe um teto diário configurado que ainda não é somado automaticamente. Também falha fechada.
`amount_mismatch`	422	O `amountCents` não corresponde ao valor que o BR Code cobra.
`payment_pending_confirmation`	409	O resultado do pagamento ainda não foi confirmado. Exige análise operacional, nunca retentativa automática.

Limite de uso

Código	HTTP	Quando acontece
`rate_limit_exceeded`	429	Excesso de requisições no minuto corrente, por IP ou por credencial. A resposta traz `Retry-After: 60`. O teto por credencial é de 300 requisições por minuto.

Indisponibilidade

Código	HTTP	Quando acontece
`service_unavailable`	503	Um serviço a montante está indisponível no momento.
`service_error`	503	Falha interna ao processar a requisição.
`nonce_store_unavailable`	503	O controle de repetição de assinatura não pôde ser consultado.
`rate_limit_store_unavailable`	503	O contador de requisições por credencial não pôde ser consultado.
`internal_error`	500	Falha não tratada. Não é esperada: se repetir, abra um chamado com o horário da chamada.

Um 422 invalid_request nem sempre é culpa do seu payload. Erros do provedor nunca aparecem em estado bruto, mas a tradução depende do tipo: indisponibilidade e falha de autenticação viram 503, enquanto uma recusa do provedor vira 422 invalid_request. Se o corpo passou na validação de campos e ainda assim voltou 422, o motivo pode estar do lado do provedor, não do seu.

Política de retry

Repita automaticamente apenas:

409 request_in_progress

Aguarde e tente de novo. A primeira requisição ainda está rodando.

429

Espere o Retry-After (60 s) antes da próxima tentativa.

503

Backoff exponencial. Vale para os quatro códigos 503.

Não repita automaticamente:

idempotency_conflict: corrija o corpo ou use uma chave nova.
payment_pending_confirmation: exige decisão de um operador.
500 internal_error: uma retentativa isolada é aceitável, mas não entre em laço. Se repetir, é problema nosso, não seu.
Qualquer outro 4xx: é erro de requisição, repetir não muda o resultado.

Toda retentativa precisa de X-Timestamp novo e assinatura nova. Uma assinatura já usada é recusada como repetição, e você recebe 401 no lugar do erro real. Mantenha a mesma Idempotency-Key para que a operação continue sendo a mesma.

Exemplo de retry

const RETRIAVEIS = new Set([
  "request_in_progress",
  "rate_limit_exceeded",
  "rate_limit_store_unavailable",
  "nonce_store_unavailable",
  "service_unavailable",
  "service_error",
]);

async function chamarComRetry(fazerRequisicao, tentativas = 4) {
  for (let i = 0; i < tentativas; i += 1) {
    // Assine de novo a cada volta: a assinatura anterior já foi consumida.
    const res = await fazerRequisicao();
    if (res.ok) return res.json();

    const corpo = await res.json().catch(() => ({}));
    if (!RETRIAVEIS.has(corpo.code) || i === tentativas - 1) throw corpo;

    const retryAfter = Number(res.headers.get("retry-after") ?? 0) * 1000;
    await new Promise((r) => setTimeout(r, retryAfter || 2 ** i * 500));
  }
}

Comece aqui

Fundamentos

Contas

Movimentação

Autenticação e autorização

Conta e vínculo

Abertura de conta

Validação e idempotência

Dinheiro

Limite de uso

Indisponibilidade

Política de retry

409 request_in_progress

429

503

Exemplo de retry

​Autenticação e autorização

​Conta e vínculo

​Abertura de conta

​Validação e idempotência

​Dinheiro

​Limite de uso

​Indisponibilidade

​Política de retry

409 request_in_progress

429

503

​Exemplo de retry

Autenticação e autorização

Conta e vínculo

Abertura de conta

Validação e idempotência

Dinheiro

Limite de uso

Indisponibilidade

Política de retry

Exemplo de retry