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"
}
Campo Tipo Descrição requestIdstring UUID único para rastreio statusnumber Código HTTP successboolean Sempre false em erros messagestring Descrição legível do erro hintstring Sugestão de como resolver codestring Código de erro programático
Códigos HTTP
Sucesso (2xx)
Código Nome Descrição 200 OK Requisição bem-sucedida 201 Created Recurso criado com sucesso
Erros do Cliente (4xx)
Código Nome Descrição 400 Bad Request Requisição malformada ou parâmetros inválidos 401 Unauthorized Credenciais ausentes ou inválidas 403 Forbidden IP não permitido ou acesso negado 404 Not Found Recurso não encontrado 409 Conflict Conflito de idempotência ou estado 422 Unprocessable Entity Dados válidos mas não processáveis 429 Too Many Requests Rate limit excedido
Erros do Servidor (5xx)
Código Nome Descrição 500 Internal Server Error Erro interno (contate suporte) 502 Bad Gateway Serviço temporariamente indisponível 503 Service Unavailable Manutenção ou sobrecarga 504 Gateway Timeout Timeout de serviço externo
Códigos de Erro Específicos
Autenticação
Código HTTP Descrição Solução UNAUTHORIZED401 Credenciais inválidas Verifique API Key e Secret TOKEN_INVALID401 Token inválido ou expirado Gere um novo token TOKEN_MISSING401 Token não fornecido Inclua token no header TOKEN_EXPIRED401 Token expirado Gere um novo token UNAUTHORIZED_ACCESS403 Acesso não autorizado Verifique permissões do usuário API_KEY_NOT_FOUND404 API Key não existe Gere uma nova credencial IP_NOT_ALLOWED403 IP não na allowlist Adicione seu IP no painel ACCESS_DENIED403 Acesso negado Verifique permissões
Validação
Código HTTP Descrição Solução VALIDATION_ERROR400 Campo obrigatório ausente Verifique campos required FIELD_REQUIRED400 Campo obrigatório Forneça o campo faltante INVALID_FIELD400 Campo com formato inválido Verifique o formato INVALID_AMOUNT400 Valor inválido Use número positivo INVALID_PIX_KEY400 Chave PIX inválida Verifique formato da chave INVALID_CPF_CNPJ400 CPF/CNPJ inválido Use apenas números INVALID_CPF400 CPF inválido Verifique o CPF INVALID_CNPJ400 CNPJ inválido Verifique o CNPJ INVALID_EMAIL400 Email inválido Use formato válido INVALID_PHONE400 Telefone inválido Use formato +55… INVALID_DATE_RANGE400 Range de datas inválido Verifique início e fim INVALID_REQUEST400 Requisição inválida Verifique parâmetros
Recursos
Código HTTP Descrição Solução RESOURCE_NOT_FOUND404 Recurso não encontrado Verifique o ID informado USER_NOT_FOUND404 Usuário não encontrado Verifique o userId USER_ALREADY_EXISTS409 Usuário já existe Use outro email/documento USER_ALREADY_BLOCKED400 Usuário já está bloqueado Usuário já bloqueado USER_NOT_BLOCKED400 Usuário não está bloqueado Usuário não está bloqueado BANK_ACCOUNT_NOT_FOUND404 Conta bancária não encontrada Verifique o accountId ACCOUNT_BLOCKED403 Conta bloqueada Contate suporte WEBHOOK_CONFIG_NOT_FOUND404 Config webhook não encontrada Verifique o configId FEE_TIER_NOT_FOUND404 Tabela de taxas não encontrada Configure tabela de taxas LIMIT_RULE_NOT_FOUND404 Regra de limite não encontrada Configure regras de limite
PIX IN
Código HTTP Descrição Solução QRCODE_EXPIRED400 QR Code expirado Gere um novo QR Code QRCODE_NOT_FOUND404 QR Code não existe Verifique o txId INVALID_QR_CODE400 QR Code inválido Verifique o formato do QR REFUND_NOT_ALLOWED400 Estorno não permitido Verifique prazo de estorno ALREADY_REFUNDED400 Já foi estornado Transação já foi estornada REFUND_FAILED400 Falha no estorno Tente novamente ou contate suporte INSUFFICIENT_BALANCE400 Saldo insuficiente Deposite mais fundos PIX_IN_PROCESSING400 PIX em processamento Aguarde e tente novamente TRANSACTION_NOT_FOUND404 Transação não encontrada Verifique o endToEndId ENTRY_NOT_FOUND404 Entrada ledger não existe Verifique o ID da entrada NOT_A_REFUND400 Transação não é estorno Use transação de estorno
Consulta DICT (Chaves PIX)
Erros retornados ao consultar chaves PIX no DICT (Diretório de Identificadores de Contas Transacionais):
Código HTTP Descrição Solução DICT_KEY_NOT_FOUND404 Chave PIX não encontrada no DICT A chave não existe ou está inativa. Verifique e tente novamente DICT_ENTRY_FRAUD_RESTRICTED400 Chave vinculada a conta com suspeita de fraude Conta ou usuário restrito por suspeita fundamentada de fraude DICT_ENTRY_USER_RESTRICTED400 Chave vinculada a usuário com restrição Usuário associado à chave possui restrições. Transação não permitida DICT_ENTRY_ACCOUNT_RESTRICTED400 Chave vinculada a conta restrita Conta associada à chave possui restrições. Transação não permitida DICT_ENTRY_OWNERSHIP_CONFLICT400 Conflito de titularidade na chave A chave possui conflito de titularidade. Verifique com o recebedor DICT_QUERY_FORBIDDEN403 Consulta DICT negada Operação negada pelo Banco Central DICT_QUERY_RATE_LIMITED429 Limite de consultas DICT excedido Muitas consultas em pouco tempo. Aguarde alguns minutos DICT_QUERY_ERROR502 Erro ao consultar chave no DICT Erro na comunicação com o DICT. Tente novamente DICT_SERVICE_TIMEOUT504 Timeout na consulta DICT Serviç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ódigo HTTP Descrição Solução TRANSFER_FAILED400 Transferência falhou Verifique dados do destinatário PIX_KEY_NOT_FOUND404 Chave PIX não existe Confirme a chave com destinatário PIX_KEY_ALREADY_EXISTS409 Chave PIX já existe Use outra chave PIX_KEY_CREATION_BLOCKED400 Criação de chave bloqueada Conta bloqueada para novas chaves DAILY_LIMIT_EXCEEDED400 Limite diário excedido Aguarde próximo dia BLOCKED_RECIPIENT403 Destinatário bloqueado Contate suporte TRANSFER_WRONG_STATUS400 Status da transferência inválido Verifique status atual ENDTOEND_ALREADY_EXISTS409 EndToEndId já existe Use outro endToEndId (idempotência) WITHDRAWAL_RESTRICTION_BLOCKED422 Conta restrita para saques por tipo de documento Verifique as configurações de restrição da conta
Chaves PIX BaaS
Erros específicos para gerenciamento de chaves PIX via API BaaS:
Código HTTP Descrição Solução BAAS_PIX_KEY_NOT_FOUND404 Chave PIX não encontrada Verifique o ID da chave BAAS_PIX_KEY_WRONG_ACCOUNT400 Chave não pertence à conta Use o accountId correto BAAS_PIX_KEY_COOLDOWN429 Aguarde entre criações de chaves Aguarde 10 minutos entre criações BAAS_PIX_KEY_LIMIT_EXCEEDED400 Limite de chaves excedido PF: 5 chaves, PJ: 20 chaves BAAS_PIX_KEY_INVALID_FORMAT400 Formato de chave inválido Verifique o formato para o tipo de chave BAAS_PIX_KEY_EVP_NO_KEY400 EVP não deve enviar pixKey Não envie pixKey para tipo EVP BAAS_PIX_KEY_DOC_MISMATCH400 CPF/CNPJ diferente do documento CPF/CNPJ deve ser igual ao da conta BAAS_PIX_KEY_ALREADY_EXISTS409 Chave já cadastrada no sistema Use outra chave ou consulte as existentes BAAS_PIX_KEY_OTHER_PARTICIPANT409 Chave cadastrada em outra instituição Solicite portabilidade ou delete no banco atual BAAS_PIX_KEY_OTHER_OWNER409 Chave pertence a outra pessoa Esta chave está vinculada a outro CPF/CNPJ BAAS_PIX_KEY_IS_CURRENT400 Não pode deletar chave corrente Defina outra chave como corrente primeiro
Limites e Horários
Código HTTP Descrição Solução LIMIT_EXCEEDED_PER_TX422 Limite por transação excedido Reduza o valor LIMIT_EXCEEDED_DAILY422 Limite diário excedido Aguarde próximo dia LIMIT_EXCEEDED_MONTHLY422 Limite mensal excedido Aguarde próximo mês LIMIT_EXCEEDED_PER_TX_NIGHT422 Limite noturno excedido Reduza valor ou aguarde até 08h (horário noturno: 20h–08h) REQUEST_FORBIDDEN_TIME422 Horário não permitido Aguarde horário permitido (horário noturno: 20h–08h)
MED (Mecanismo Especial de Devolução)
Código HTTP Descrição Solução MED_NOT_FOUND404 MED não encontrado Verifique o ID do MED MED_NOT_AWAITING_DEFENSE400 MED não aguarda defesa MED já respondido ou expirado MED_DEFENSE_FILE_REQUIRED400 Arquivo de defesa obrigatório Envie arquivo de defesa
BaaS (Banking as a Service)
Erros específicos para integrações BaaS:
Usuário BaaS
Código HTTP Descrição Solução BAAS_USER_NOT_FOUND404 Usuário não encontrado Verifique se o ID do usuário está correto BAAS_USER_NOT_BAAS400 Este usuário não é uma conta BaaS Operação requer conta BaaS válida BAAS_USER_WRONG_PARTNER403 Usuário não pertence ao seu parceiro Acesse usuários do seu próprio parceiro BAAS_USER_NO_DOCUMENT400 Usuário sem CPF/CNPJ cadastrado Usuário precisa de documento cadastrado
Conta BaaS
Código HTTP Descrição Solução BAAS_ACCOUNT_NOT_FOUND404 Conta não encontrada Verifique se o accountId está correto BAAS_ACCOUNT_NOT_BAAS400 Esta conta não é uma conta BaaS Operação requer conta BaaS válida BAAS_ACCOUNT_WRONG_PARTNER403 Conta não pertence ao seu parceiro Acesse contas do seu próprio parceiro BAAS_ACCOUNT_ID_REQUIRED400 accountId é obrigatório Forneça accountId no formato UUID
Configuração e Documento
Código HTTP Descrição Solução BAAS_CONFIG_INACTIVE403 API Key sem configuração BaaS ativa Contate suporte para ativar configuração BaaS BAAS_DOCUMENT_BLOCKED403 Documento bloqueado Este documento está bloqueado. Contate suporte
Email e Verificação
Código HTTP Descrição Solução BAAS_EMAIL_ALREADY_VERIFIED400 Email já foi verificado Email já está verificado BAAS_EMAIL_NOT_VERIFIED400 Email não verificado Cliente deve verificar email antes BAAS_EMAIL_HAS_ACCOUNT400 Email já possui conta bancária ativa Este email já está associado a uma conta BAAS_EMAIL_KYC_IN_PROGRESS400 Email com KYC em andamento Aguarde conclusão ou use outro email BAAS_RESEND_EMAIL_FAILED500 Erro ao reenviar email Tente novamente em alguns instantes
CPF
Código HTTP Descrição Solução BAAS_CPF_HAS_ACCOUNT400 CPF já possui conta bancária Este CPF já está associado a uma conta BAAS_CPF_KYC_IN_PROGRESS400 CPF com KYC em andamento Aguarde a conclusão do processo
Criação e Onboarding
Código HTTP Descrição Solução BAAS_USER_CREATION_FAILED500 Erro ao criar usuário Tente novamente BAAS_PROPOSAL_CREATION_FAILED500 Erro ao criar proposta Tente novamente BAAS_KYC_LINK_GENERATION_FAILED500 Erro ao gerar link de verificação Tente novamente BAAS_CAF_NO_EXECUTION_ID500 Erro na comunicação com serviço de KYC Tente novamente ou contate suporte
Upload de Documentos
Código HTTP Descrição Solução BAAS_UPLOAD_NOT_ALLOWED_LIVENESS400 Upload não permitido para onboarding liveness Complete o KYC pela URL fornecida BAAS_DOCUMENTS_ALREADY_SENT400 Documentos já enviados ou KYC processado Consulte o status do onboarding
Pagamentos BaaS
Código HTTP Descrição Solução BAAS_INVALID_QRCODE400 QR Code inválido Verifique ou escaneie novamente BAAS_PAYMENT_NOT_FOUND404 Pagamento não encontrado Verifique o ID ou endToEndId BAAS_PAYMENT_WRONG_ACCOUNT400 Pagamento não pertence à conta informada Use a conta correta para consultar
2FA (Autenticação de Dois Fatores)
Código HTTP Descrição Solução INVALID_2FA_CODE400 Código de 2FA inválido Verifique os 6 dígitos digitados EXPIRED_2FA_CODE400 Código de 2FA expirado Solicite 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ódigo HTTP Descrição Solução KYC_ALREADY_APPROVED400 KYC já foi aprovado Usuário já está verificado KYC_PENDING400 KYC pendente de análise Aguarde a análise ser concluída KYC_REJECTED400 KYC foi rejeitado Verifique os dados e tente novamente KYC_EXPIRED400 KYC expirado Inicie um novo processo de KYC KYC_IN_PROCESSING400 KYC em processamento Aguarde a conclusão KYB_ALREADY_APPROVED400 KYB já foi aprovado Empresa já está verificada KYB_PENDING400 KYB pendente de análise Aguarde a análise ser concluída
Pré-requisitos
Código HTTP Descrição Solução CPF_NOT_FOUND404 CPF não encontrado Cadastre o CPF antes CNPJ_NOT_FOUND404 CNPJ não encontrado Cadastre o CNPJ antes EMAIL_NOT_VERIFIED_KYC400 Email não verificado Verifique o email antes do KYC PHONE_NOT_VERIFIED_KYC400 Telefone não verificado Verifique o telefone antes do KYC KYC_STEP_INVALID400 Etapa do KYC inválida Complete as etapas anteriores
Documentos
Código HTTP Descrição Solução NO_DOCUMENTS_FOUND404 Nenhum documento encontrado Envie os documentos necessários DOCUMENT_REQUIRED400 Documento obrigatório Envie o documento solicitado DOCUMENT_FRONT_OR_SELFIE_REQUIRED400 Frente do doc ou selfie obrig. Envie frente ou selfie DOCUMENT_NOT_FOUND404 Documento não encontrado Verifique o ID do documento DOCUMENT_UPLOAD_FAILED500 Falha no upload do documento Tente novamente DOCUMENT_INVALID_FORMAT400 Formato de documento inválido Use JPG, PNG ou PDF
Sócios/Representantes
Código HTTP Descrição Solução PARTNER_NOT_FOUND404 Sócio não encontrado Verifique o ID do sócio PARTNER_ALREADY_EXISTS409 Sócio já cadastrado Sócio já está vinculado PARTNER_HAS_PENDING_KYC400 Sócio tem KYC pendente Aguarde KYC do sócio
Códigos BACEN/SPI
Erros retornados pelo Sistema de Pagamentos Instantâneos (SPI) do Banco Central:
Código Categoria Significado Descrição AB03Liquidação Timeout no SPI Liquidação interrompida por timeout no Sistema de Pagamentos Instantâneos AB09Liquidação Erro no participante recebedor Erro no PSP (banco) do usuário recebedor ao processar a requisição AC03Conta Número de conta inválido Agência e/ou conta do recebedor inexistente ou inválida AC06Conta Conta bloqueada Conta especificada está bloqueada para lançamentos AC07Conta Conta encerrada Conta transacional encerrada no PSP do Recebedor AC14Conta Tipo de conta inválido Tipo incorreto para a conta transacional especificada AG03Operação Transação não suportada Tipo de transação não suportado/autorizado na conta AM02Montante Valor supera limite Valor superior ao limite permitido para o tipo de conta AM09Montante Valor não corresponde Devolução em valor que supera a ordem de pagamento original BE01Identificação CPF/CNPJ inconsistente CPF/CNPJ não consistente com titular da conta BE17Identificação QR Code rejeitado QR Code rejeitado pelo participante do recebedor CH11CPF/CNPJ CPF/CNPJ incorreto CPF/CNPJ do recebedor informado está incorreto ou inválido DS04Processamento Ordem rejeitada pelo recebedor Rejeitada pelo PSP do Recebedor por motivos operacionais DS24Processamento Timeout em autorização Timeout entre PAIN.013 e PACS.008 (autorização recorrente) DT05Data Data inválida ou expirada Data de corte inválida ou expirada RR04Regulação Motivo regulatório Rejeição por conformidade regulatória ou exigências legais SL02Liquidação Número de conta inválido Conta 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ódigo HTTP Descrição Solução WEBHOOK_NOT_FOUND404 Webhook não existe Verifique configId INVALID_URL400 URL inválida Use HTTPS válido DUPLICATE_WEBHOOK409 Webhook duplicado Use URL diferente
Rate Limiting
Código HTTP Descrição Solução RATE_LIMIT_EXCEEDED429 Muitas requisições Aguarde e implemente backoff
Erros de Sistema
Código HTTP Descrição Solução INTERNAL_ERROR500 Erro interno do servidor Tente novamente ou contate suporte SERVICE_UNAVAILABLE503 Serviço indisponível Aguarde e tente novamente TIMEOUT504 Timeout da requisição Tente novamente EXTERNAL_SERVICE_ERROR502 Erro em serviço externo Tente 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.