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
API_KEY_NOT_FOUND404API Key não existeGere uma nova credencial
IP_NOT_ALLOWED403IP não na allowlistAdicione seu IP no painel

Validação

CódigoHTTPDescriçãoSolução
VALIDATION_ERROR400Campo obrigatório ausenteVerifique campos required
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

PIX IN

CódigoHTTPDescriçãoSolução
QRCODE_EXPIRED400QR Code expiradoGere um novo QR Code
QRCODE_NOT_FOUND404QR Code não existeVerifique o txId
REFUND_NOT_ALLOWED400Estorno não permitidoVerifique prazo de estorno
INSUFFICIENT_BALANCE400Saldo insuficienteDeposite mais fundos

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
DAILY_LIMIT_EXCEEDED400Limite diário excedidoAguarde próximo dia
BLOCKED_RECIPIENT403Destinatário bloqueadoContate suporte

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

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.