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 |
|---|
requestId | string | UUID único para rastreio |
status | number | Código HTTP |
success | boolean | Sempre false em erros |
message | string | Descrição legível do erro |
hint | string | Sugestão de como resolver |
code | string | 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 |
|---|
UNAUTHORIZED | 401 | Credenciais inválidas | Verifique API Key e Secret |
API_KEY_NOT_FOUND | 404 | API Key não existe | Gere uma nova credencial |
IP_NOT_ALLOWED | 403 | IP não na allowlist | Adicione seu IP no painel |
Validação
| Código | HTTP | Descrição | Solução |
|---|
VALIDATION_ERROR | 400 | Campo obrigatório ausente | Verifique campos required |
INVALID_AMOUNT | 400 | Valor inválido | Use número positivo |
INVALID_PIX_KEY | 400 | Chave PIX inválida | Verifique formato da chave |
INVALID_CPF_CNPJ | 400 | CPF/CNPJ inválido | Use apenas números |
PIX IN
| Código | HTTP | Descrição | Solução |
|---|
QRCODE_EXPIRED | 400 | QR Code expirado | Gere um novo QR Code |
QRCODE_NOT_FOUND | 404 | QR Code não existe | Verifique o txId |
REFUND_NOT_ALLOWED | 400 | Estorno não permitido | Verifique prazo de estorno |
INSUFFICIENT_BALANCE | 400 | Saldo insuficiente | Deposite mais fundos |
PIX OUT
| Código | HTTP | Descrição | Solução |
|---|
TRANSFER_FAILED | 400 | Transferência falhou | Verifique dados do destinatário |
PIX_KEY_NOT_FOUND | 404 | Chave PIX não existe | Confirme a chave com destinatário |
DAILY_LIMIT_EXCEEDED | 400 | Limite diário excedido | Aguarde próximo dia |
BLOCKED_RECIPIENT | 403 | Destinatário bloqueado | Contate suporte |
Códigos BACEN/SPI
Erros retornados pelo Sistema de Pagamentos Instantâneos (SPI) do Banco Central:
| Código | Categoria | Significado | Descrição |
|---|
AB03 | Liquidação | Timeout no SPI | Liquidação interrompida por timeout no Sistema de Pagamentos Instantâneos |
AB09 | Liquidação | Erro no participante recebedor | Erro no PSP (banco) do usuário recebedor ao processar a requisição |
AC03 | Conta | Número de conta inválido | Agência e/ou conta do recebedor inexistente ou inválida |
AC06 | Conta | Conta bloqueada | Conta especificada está bloqueada para lançamentos |
AC07 | Conta | Conta encerrada | Conta transacional encerrada no PSP do Recebedor |
AC14 | Conta | Tipo de conta inválido | Tipo incorreto para a conta transacional especificada |
AG03 | Operação | Transação não suportada | Tipo de transação não suportado/autorizado na conta |
AM02 | Montante | Valor supera limite | Valor superior ao limite permitido para o tipo de conta |
AM09 | Montante | Valor não corresponde | Devolução em valor que supera a ordem de pagamento original |
BE01 | Identificação | CPF/CNPJ inconsistente | CPF/CNPJ não consistente com titular da conta |
BE17 | Identificação | QR Code rejeitado | QR Code rejeitado pelo participante do recebedor |
CH11 | CPF/CNPJ | CPF/CNPJ incorreto | CPF/CNPJ do recebedor informado está incorreto ou inválido |
DS04 | Processamento | Ordem rejeitada pelo recebedor | Rejeitada pelo PSP do Recebedor por motivos operacionais |
DS24 | Processamento | Timeout em autorização | Timeout entre PAIN.013 e PACS.008 (autorização recorrente) |
DT05 | Data | Data inválida ou expirada | Data de corte inválida ou expirada |
RR04 | Regulação | Motivo regulatório | Rejeição por conformidade regulatória ou exigências legais |
SL02 | Liquidaçã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_FOUND | 404 | Webhook não existe | Verifique configId |
INVALID_URL | 400 | URL inválida | Use HTTPS válido |
DUPLICATE_WEBHOOK | 409 | Webhook duplicado | Use URL diferente |
Rate Limiting
| Código | HTTP | Descrição | Solução |
|---|
RATE_LIMIT_EXCEEDED | 429 | Muitas requisições | Aguarde 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.