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 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_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 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
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
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)
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.