Skip to main content

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
TOKEN_EXPIRED401Token expiradoGere um novo token
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_CPF400CPF inválidoVerifique o CPF
INVALID_CNPJ400CNPJ inválidoVerifique o CNPJ
INVALID_EMAIL400Email inválidoUse formato válido
INVALID_PHONE400Telefone inválidoUse formato +55…
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
USER_ALREADY_EXISTS409Usuário já existeUse outro email/documento
USER_ALREADY_BLOCKED400Usuário já está bloqueadoUsuário já bloqueado
USER_NOT_BLOCKED400Usuário não está bloqueadoUsuário não está bloqueado
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

Chaves PIX BaaS

Erros específicos para gerenciamento de chaves PIX via API BaaS:
CódigoHTTPDescriçãoSolução
BAAS_PIX_KEY_NOT_FOUND404Chave PIX não encontradaVerifique o ID da chave
BAAS_PIX_KEY_WRONG_ACCOUNT400Chave não pertence à contaUse o accountId correto
BAAS_PIX_KEY_COOLDOWN429Aguarde entre criações de chavesAguarde 10 minutos entre criações
BAAS_PIX_KEY_LIMIT_EXCEEDED400Limite de chaves excedidoPF: 5 chaves, PJ: 20 chaves
BAAS_PIX_KEY_INVALID_FORMAT400Formato de chave inválidoVerifique o formato para o tipo de chave
BAAS_PIX_KEY_EVP_NO_KEY400EVP não deve enviar pixKeyNão envie pixKey para tipo EVP
BAAS_PIX_KEY_DOC_MISMATCH400CPF/CNPJ diferente do documentoCPF/CNPJ deve ser igual ao da conta
BAAS_PIX_KEY_ALREADY_EXISTS409Chave já cadastrada no sistemaUse outra chave ou consulte as existentes
BAAS_PIX_KEY_OTHER_PARTICIPANT409Chave cadastrada em outra instituiçãoSolicite portabilidade ou delete no banco atual
BAAS_PIX_KEY_OTHER_OWNER409Chave pertence a outra pessoaEsta chave está vinculada a outro CPF/CNPJ
BAAS_PIX_KEY_IS_CURRENT400Não pode deletar chave correnteDefina outra chave como corrente primeiro

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

BaaS (Banking as a Service)

Erros específicos para integrações BaaS:

Usuário BaaS

CódigoHTTPDescriçãoSolução
BAAS_USER_NOT_FOUND404Usuário não encontradoVerifique se o ID do usuário está correto
BAAS_USER_NOT_BAAS400Este usuário não é uma conta BaaSOperação requer conta BaaS válida
BAAS_USER_WRONG_PARTNER403Usuário não pertence ao seu parceiroAcesse usuários do seu próprio parceiro
BAAS_USER_NO_DOCUMENT400Usuário sem CPF/CNPJ cadastradoUsuário precisa de documento cadastrado

Conta BaaS

CódigoHTTPDescriçãoSolução
BAAS_ACCOUNT_NOT_FOUND404Conta não encontradaVerifique se o accountId está correto
BAAS_ACCOUNT_NOT_BAAS400Esta conta não é uma conta BaaSOperação requer conta BaaS válida
BAAS_ACCOUNT_WRONG_PARTNER403Conta não pertence ao seu parceiroAcesse contas do seu próprio parceiro
BAAS_ACCOUNT_ID_REQUIRED400accountId é obrigatórioForneça accountId no formato UUID

Configuração e Documento

CódigoHTTPDescriçãoSolução
BAAS_CONFIG_INACTIVE403API Key sem configuração BaaS ativaContate suporte para ativar configuração BaaS
BAAS_DOCUMENT_BLOCKED403Documento bloqueadoEste documento está bloqueado. Contate suporte

Email e Verificação

CódigoHTTPDescriçãoSolução
BAAS_EMAIL_ALREADY_VERIFIED400Email já foi verificadoEmail já está verificado
BAAS_EMAIL_NOT_VERIFIED400Email não verificadoCliente deve verificar email antes
BAAS_EMAIL_HAS_ACCOUNT400Email já possui conta bancária ativaEste email já está associado a uma conta
BAAS_EMAIL_KYC_IN_PROGRESS400Email com KYC em andamentoAguarde conclusão ou use outro email
BAAS_RESEND_EMAIL_FAILED500Erro ao reenviar emailTente novamente em alguns instantes

CPF

CódigoHTTPDescriçãoSolução
BAAS_CPF_HAS_ACCOUNT400CPF já possui conta bancáriaEste CPF já está associado a uma conta
BAAS_CPF_KYC_IN_PROGRESS400CPF com KYC em andamentoAguarde a conclusão do processo

Criação e Onboarding

CódigoHTTPDescriçãoSolução
BAAS_USER_CREATION_FAILED500Erro ao criar usuárioTente novamente
BAAS_PROPOSAL_CREATION_FAILED500Erro ao criar propostaTente novamente
BAAS_KYC_LINK_GENERATION_FAILED500Erro ao gerar link de verificaçãoTente novamente
BAAS_CAF_NO_EXECUTION_ID500Erro na comunicação com serviço de KYCTente novamente ou contate suporte

Upload de Documentos

CódigoHTTPDescriçãoSolução
BAAS_UPLOAD_NOT_ALLOWED_LIVENESS400Upload não permitido para onboarding livenessComplete o KYC pela URL fornecida
BAAS_DOCUMENTS_ALREADY_SENT400Documentos já enviados ou KYC processadoConsulte o status do onboarding

Pagamentos BaaS

CódigoHTTPDescriçãoSolução
BAAS_INVALID_QRCODE400QR Code inválidoVerifique ou escaneie novamente
BAAS_PAYMENT_NOT_FOUND404Pagamento não encontradoVerifique o ID ou endToEndId
BAAS_PAYMENT_WRONG_ACCOUNT400Pagamento não pertence à conta informadaUse a conta correta para consultar

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)

KYC/KYB (Verificação de Identidade)

Erros relacionados ao processo de verificação de identidade:

Status KYC

CódigoHTTPDescriçãoSolução
KYC_ALREADY_APPROVED400KYC já foi aprovadoUsuário já está verificado
KYC_PENDING400KYC pendente de análiseAguarde a análise ser concluída
KYC_REJECTED400KYC foi rejeitadoVerifique os dados e tente novamente
KYC_EXPIRED400KYC expiradoInicie um novo processo de KYC
KYC_IN_PROCESSING400KYC em processamentoAguarde a conclusão
KYB_ALREADY_APPROVED400KYB já foi aprovadoEmpresa já está verificada
KYB_PENDING400KYB pendente de análiseAguarde a análise ser concluída

Pré-requisitos

CódigoHTTPDescriçãoSolução
CPF_NOT_FOUND404CPF não encontradoCadastre o CPF antes
CNPJ_NOT_FOUND404CNPJ não encontradoCadastre o CNPJ antes
EMAIL_NOT_VERIFIED_KYC400Email não verificadoVerifique o email antes do KYC
PHONE_NOT_VERIFIED_KYC400Telefone não verificadoVerifique o telefone antes do KYC
KYC_STEP_INVALID400Etapa do KYC inválidaComplete as etapas anteriores

Documentos

CódigoHTTPDescriçãoSolução
NO_DOCUMENTS_FOUND404Nenhum documento encontradoEnvie os documentos necessários
DOCUMENT_REQUIRED400Documento obrigatórioEnvie o documento solicitado
DOCUMENT_FRONT_OR_SELFIE_REQUIRED400Frente do doc ou selfie obrig.Envie frente ou selfie
DOCUMENT_NOT_FOUND404Documento não encontradoVerifique o ID do documento
DOCUMENT_UPLOAD_FAILED500Falha no upload do documentoTente novamente
DOCUMENT_INVALID_FORMAT400Formato de documento inválidoUse JPG, PNG ou PDF

Sócios/Representantes

CódigoHTTPDescriçãoSolução
PARTNER_NOT_FOUND404Sócio não encontradoVerifique o ID do sócio
PARTNER_ALREADY_EXISTS409Sócio já cadastradoSócio já está vinculado
PARTNER_HAS_PENDING_KYC400Sócio tem KYC pendenteAguarde KYC do sócio

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.