Pular para o conteúdo principal

Estrutura de Erro

Quando ocorre um erro, a API retorna uma resposta padronizada:
{
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "method": "POST",
  "url": "/v4/i/pix/in/dynamic-qrcode",
  "status": 400,
  "success": false,
  "message": "Descrição do erro",
  "hint": "Sugestão de correção",
  "code": "VALIDATION_ERROR",
  "codeMessage": "Detalhes adicionais"
}
CampoTipoDescrição
requestIdstringUUID único para rastreio
statusnumberCódigo HTTP
successbooleanSempre false em erros
messagestringDescrição legível do erro
hintstringSugestão de como resolver
codestringCódigo de erro programático

Códigos HTTP

Sucesso (2xx)

CódigoNomeDescrição
200OKRequisição bem-sucedida
201CreatedRecurso criado com sucesso

Erros do Cliente (4xx)

CódigoNomeDescrição
400Bad RequestRequisição malformada ou parâmetros inválidos
401UnauthorizedCredenciais ausentes ou inválidas
403ForbiddenIP não permitido ou acesso negado
404Not FoundRecurso não encontrado
409ConflictConflito de idempotência ou estado
422Unprocessable EntityDados válidos mas não processáveis
429Too Many RequestsRate limit excedido

Erros do Servidor (5xx)

CódigoNomeDescrição
500Internal Server ErrorErro interno (contate suporte)
502Bad GatewayServiço temporariamente indisponível
503Service UnavailableManutenção ou sobrecarga
504Gateway TimeoutTimeout de serviço externo

Códigos de Erro Específicos

Autenticação

CódigoHTTPDescriçãoSolução
UNAUTHORIZED401Credenciais inválidasVerifique API Key e Secret
TOKEN_INVALID401Token inválido ou expiradoGere um novo token
TOKEN_MISSING401Token não fornecidoInclua token no header
UNAUTHORIZED_ACCESS403Acesso não autorizadoVerifique permissões do usuário
API_KEY_NOT_FOUND404API Key não existeGere uma nova credencial
IP_NOT_ALLOWED403IP não na allowlistAdicione seu IP no painel
ACCESS_DENIED403Acesso negadoVerifique permissões

Validação

CódigoHTTPDescriçãoSolução
VALIDATION_ERROR400Campo obrigatório ausenteVerifique campos required
FIELD_REQUIRED400Campo obrigatórioForneça o campo faltante
INVALID_FIELD400Campo com formato inválidoVerifique o formato
INVALID_AMOUNT400Valor inválidoUse número positivo
INVALID_PIX_KEY400Chave PIX inválidaVerifique formato da chave
INVALID_CPF_CNPJ400CPF/CNPJ inválidoUse apenas números
INVALID_DATE_RANGE400Range de datas inválidoVerifique início e fim
INVALID_REQUEST400Requisição inválidaVerifique parâmetros

Recursos

CódigoHTTPDescriçãoSolução
RESOURCE_NOT_FOUND404Recurso não encontradoVerifique o ID informado
USER_NOT_FOUND404Usuário não encontradoVerifique o userId
BANK_ACCOUNT_NOT_FOUND404Conta bancária não encontradaVerifique o accountId
ACCOUNT_BLOCKED403Conta bloqueadaContate suporte
WEBHOOK_CONFIG_NOT_FOUND404Config webhook não encontradaVerifique o configId
FEE_TIER_NOT_FOUND404Tabela de taxas não encontradaConfigure tabela de taxas
LIMIT_RULE_NOT_FOUND404Regra de limite não encontradaConfigure regras de limite

PIX IN

CódigoHTTPDescriçãoSolução
QRCODE_EXPIRED400QR Code expiradoGere um novo QR Code
QRCODE_NOT_FOUND404QR Code não existeVerifique o txId
INVALID_QR_CODE400QR Code inválidoVerifique o formato do QR
REFUND_NOT_ALLOWED400Estorno não permitidoVerifique prazo de estorno
ALREADY_REFUNDED400Já foi estornadoTransação já foi estornada
REFUND_FAILED400Falha no estornoTente novamente ou contate suporte
INSUFFICIENT_BALANCE400Saldo insuficienteDeposite mais fundos
PIX_IN_PROCESSING400PIX em processamentoAguarde e tente novamente
TRANSACTION_NOT_FOUND404Transação não encontradaVerifique o endToEndId
ENTRY_NOT_FOUND404Entrada ledger não existeVerifique o ID da entrada
NOT_A_REFUND400Transação não é estornoUse transação de estorno

Consulta DICT (Chaves PIX)

Erros retornados ao consultar chaves PIX no DICT (Diretório de Identificadores de Contas Transacionais):
CódigoHTTPDescriçãoSolução
DICT_KEY_NOT_FOUND404Chave PIX não encontrada no DICTA chave não existe ou está inativa. Verifique e tente novamente
DICT_ENTRY_FRAUD_RESTRICTED400Chave vinculada a conta com suspeita de fraudeConta ou usuário restrito por suspeita fundamentada de fraude
DICT_ENTRY_USER_RESTRICTED400Chave vinculada a usuário com restriçãoUsuário associado à chave possui restrições. Transação não permitida
DICT_ENTRY_ACCOUNT_RESTRICTED400Chave vinculada a conta restritaConta associada à chave possui restrições. Transação não permitida
DICT_ENTRY_OWNERSHIP_CONFLICT400Conflito de titularidade na chaveA chave possui conflito de titularidade. Verifique com o recebedor
DICT_QUERY_FORBIDDEN403Consulta DICT negadaOperação negada pelo Banco Central
DICT_QUERY_RATE_LIMITED429Limite de consultas DICT excedidoMuitas consultas em pouco tempo. Aguarde alguns minutos
DICT_QUERY_ERROR502Erro ao consultar chave no DICTErro na comunicação com o DICT. Tente novamente
DICT_SERVICE_TIMEOUT504Timeout na consulta DICTServiço DICT lento. Aguarde e tente novamente
Erros de restrição por fraude (DICT_ENTRY_FRAUD_RESTRICTED) indicam que a chave PIX consultada está associada a uma conta ou usuário com suspeita fundamentada de fraude junto ao Banco Central. Não é possível realizar transações com esta chave. Este é um mecanismo de proteção do SPI (Sistema de Pagamentos Instantâneos).

PIX OUT

CódigoHTTPDescriçãoSolução
TRANSFER_FAILED400Transferência falhouVerifique dados do destinatário
PIX_KEY_NOT_FOUND404Chave PIX não existeConfirme a chave com destinatário
PIX_KEY_ALREADY_EXISTS409Chave PIX já existeUse outra chave
PIX_KEY_CREATION_BLOCKED400Criação de chave bloqueadaConta bloqueada para novas chaves
DAILY_LIMIT_EXCEEDED400Limite diário excedidoAguarde próximo dia
BLOCKED_RECIPIENT403Destinatário bloqueadoContate suporte
TRANSFER_WRONG_STATUS400Status da transferência inválidoVerifique status atual
ENDTOEND_ALREADY_EXISTS409EndToEndId já existeUse outro endToEndId (idempotência)
WITHDRAWAL_RESTRICTION_BLOCKED422Conta restrita para saques por tipo de documentoVerifique as configurações de restrição da conta

Limites e Horários

CódigoHTTPDescriçãoSolução
LIMIT_EXCEEDED_PER_TX422Limite por transação excedidoReduza o valor
LIMIT_EXCEEDED_DAILY422Limite diário excedidoAguarde próximo dia
LIMIT_EXCEEDED_MONTHLY422Limite mensal excedidoAguarde próximo mês
LIMIT_EXCEEDED_PER_TX_NIGHT422Limite noturno excedidoReduza valor ou aguarde até 08h (horário noturno: 20h–08h)
REQUEST_FORBIDDEN_TIME422Horário não permitidoAguarde horário permitido (horário noturno: 20h–08h)

MED (Mecanismo Especial de Devolução)

CódigoHTTPDescriçãoSolução
MED_NOT_FOUND404MED não encontradoVerifique o ID do MED
MED_NOT_AWAITING_DEFENSE400MED não aguarda defesaMED já respondido ou expirado
MED_DEFENSE_FILE_REQUIRED400Arquivo de defesa obrigatórioEnvie arquivo de defesa

2FA (Autenticação de Dois Fatores)

CódigoHTTPDescriçãoSolução
INVALID_2FA_CODE400Código de 2FA inválidoVerifique os 6 dígitos digitados
EXPIRED_2FA_CODE400Código de 2FA expiradoSolicite novo código (válido por 5 min)

Códigos BACEN/SPI

Erros retornados pelo Sistema de Pagamentos Instantâneos (SPI) do Banco Central:
CódigoCategoriaSignificadoDescrição
AB03LiquidaçãoTimeout no SPILiquidação interrompida por timeout no Sistema de Pagamentos Instantâneos
AB09LiquidaçãoErro no participante recebedorErro no PSP (banco) do usuário recebedor ao processar a requisição
AC03ContaNúmero de conta inválidoAgência e/ou conta do recebedor inexistente ou inválida
AC06ContaConta bloqueadaConta especificada está bloqueada para lançamentos
AC07ContaConta encerradaConta transacional encerrada no PSP do Recebedor
AC14ContaTipo de conta inválidoTipo incorreto para a conta transacional especificada
AG03OperaçãoTransação não suportadaTipo de transação não suportado/autorizado na conta
AM02MontanteValor supera limiteValor superior ao limite permitido para o tipo de conta
AM09MontanteValor não correspondeDevolução em valor que supera a ordem de pagamento original
BE01IdentificaçãoCPF/CNPJ inconsistenteCPF/CNPJ não consistente com titular da conta
BE17IdentificaçãoQR Code rejeitadoQR Code rejeitado pelo participante do recebedor
CH11CPF/CNPJCPF/CNPJ incorretoCPF/CNPJ do recebedor informado está incorreto ou inválido
DS04ProcessamentoOrdem rejeitada pelo recebedorRejeitada pelo PSP do Recebedor por motivos operacionais
DS24ProcessamentoTimeout em autorizaçãoTimeout entre PAIN.013 e PACS.008 (autorização recorrente)
DT05DataData inválida ou expiradaData de corte inválida ou expirada
RR04RegulaçãoMotivo regulatórioRejeição por conformidade regulatória ou exigências legais
SL02LiquidaçãoNúmero de conta inválidoConta inválida para liquidação
Esses códigos são definidos pelo Banco Central do Brasil e podem ser retornados em operações PIX que envolvem comunicação com outros bancos.

Webhooks

CódigoHTTPDescriçãoSolução
WEBHOOK_NOT_FOUND404Webhook não existeVerifique configId
INVALID_URL400URL inválidaUse HTTPS válido
DUPLICATE_WEBHOOK409Webhook duplicadoUse URL diferente

Rate Limiting

CódigoHTTPDescriçãoSolução
RATE_LIMIT_EXCEEDED429Muitas requisiçõesAguarde e implemente backoff

Erros de Sistema

CódigoHTTPDescriçãoSolução
INTERNAL_ERROR500Erro interno do servidorTente novamente ou contate suporte
SERVICE_UNAVAILABLE503Serviço indisponívelAguarde e tente novamente
TIMEOUT504Timeout da requisiçãoTente novamente
EXTERNAL_SERVICE_ERROR502Erro em serviço externoTente novamente

Tratamento de Erros

Exemplo em JavaScript

async function callOwemAPI(endpoint, options) {
  try {
    const response = await fetch(`https://api.owem.com.br${endpoint}`, options)
    const data = await response.json()

    if (!data.success) {
      switch (data.status) {
        case 401:
          throw new Error("Credenciais inválidas")
        case 403:
          throw new Error("IP não permitido")
        case 429:
          // Implementar exponential backoff
          await sleep(getBackoffDelay(data))
          return callOwemAPI(endpoint, options)
        default:
          throw new Error(data.message)
      }
    }

    return data
  } catch (error) {
    console.error(`[Owem API] ${error.message}`)
    throw error
  }
}

Exemplo em Python

import requests
import time

def call_owem_api(endpoint, **kwargs):
    try:
        response = requests.request(
            url=f"https://api.owem.com.br{endpoint}",
            **kwargs
        )
        data = response.json()

        if not data.get("success"):
            status = data.get("status")

            if status == 429:
                # Exponential backoff
                time.sleep(get_backoff_delay(data))
                return call_owem_api(endpoint, **kwargs)

            raise Exception(data.get("message"))

        return data

    except requests.RequestException as e:
        print(f"[Owem API] {e}")
        raise

Boas Práticas

Log Request IDs

Sempre logue o requestId para facilitar debugging com suporte.

Exponential Backoff

Implemente retry com backoff exponencial para erros 429 e 5xx.

Circuit Breaker

Use circuit breaker para evitar cascata de falhas.

Monitoramento

Monitore taxa de erros e latência por endpoint.