Error Structure
When an error occurs, the API returns a standardized response:
{
"requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"method": "POST",
"url": "/v4/i/pix/in/dynamic-qrcode",
"status": 400,
"success": false,
"message": "Error description",
"hint": "Suggestion for correction",
"code": "VALIDATION_ERROR",
"codeMessage": "Additional details"
}
| Field | Type | Description |
|---|
requestId | string | Unique UUID for tracking |
status | number | HTTP code |
success | boolean | Always false on errors |
message | string | Human-readable error description |
hint | string | Suggestion on how to resolve |
code | string | Programmatic error code |
HTTP Codes
Success (2xx)
| Code | Name | Description |
|---|
| 200 | OK | Request successful |
| 201 | Created | Resource created successfully |
Client Errors (4xx)
| Code | Name | Description |
|---|
| 400 | Bad Request | Malformed request or invalid parameters |
| 401 | Unauthorized | Missing or invalid credentials |
| 403 | Forbidden | IP not allowed or access denied |
| 404 | Not Found | Resource not found |
| 409 | Conflict | Idempotency or state conflict |
| 422 | Unprocessable Entity | Valid data but not processable |
| 429 | Too Many Requests | Rate limit exceeded |
Server Errors (5xx)
| Code | Name | Description |
|---|
| 500 | Internal Server Error | Internal error (contact support) |
| 502 | Bad Gateway | Service temporarily unavailable |
| 503 | Service Unavailable | Maintenance or overload |
| 504 | Gateway Timeout | External service timeout |
Specific Error Codes
Authentication
| Code | HTTP | Description | Solution |
|---|
UNAUTHORIZED | 401 | Invalid credentials | Check API Key and Secret |
API_KEY_NOT_FOUND | 404 | API Key doesn’t exist | Generate a new credential |
IP_NOT_ALLOWED | 403 | IP not in allowlist | Add your IP in the dashboard |
Validation
| Code | HTTP | Description | Solution |
|---|
VALIDATION_ERROR | 400 | Required field missing | Check required fields |
INVALID_AMOUNT | 400 | Invalid value | Use positive number |
INVALID_PIX_KEY | 400 | Invalid PIX key | Check key format |
INVALID_CPF_CNPJ | 400 | Invalid CPF/CNPJ | Use numbers only |
PIX IN
| Code | HTTP | Description | Solution |
|---|
QRCODE_EXPIRED | 400 | QR Code expired | Generate a new QR Code |
QRCODE_NOT_FOUND | 404 | QR Code doesn’t exist | Check the txId |
REFUND_NOT_ALLOWED | 400 | Refund not allowed | Check refund deadline |
INSUFFICIENT_BALANCE | 400 | Insufficient balance | Deposit more funds |
PIX OUT
| Code | HTTP | Description | Solution |
|---|
TRANSFER_FAILED | 400 | Transfer failed | Check recipient data |
PIX_KEY_NOT_FOUND | 404 | PIX key doesn’t exist | Confirm key with recipient |
DAILY_LIMIT_EXCEEDED | 400 | Daily limit exceeded | Wait for next day |
BLOCKED_RECIPIENT | 403 | Blocked recipient | Contact support |
BACEN/SPI Codes
Errors returned by the Brazilian Central Bank’s Instant Payment System (SPI):
| Code | Category | Meaning | Description |
|---|
AB03 | Settlement | SPI Timeout | Settlement interrupted by timeout in the Instant Payment System |
AB09 | Settlement | Receiver participant error | Error at the receiver’s PSP (bank) when processing the request |
AC03 | Account | Invalid account number | Receiver’s branch and/or account does not exist or is invalid |
AC06 | Account | Blocked account | Specified account is blocked for transactions |
AC07 | Account | Closed account | Transactional account closed at the Receiver’s PSP |
AC14 | Account | Invalid account type | Incorrect type for the specified transactional account |
AG03 | Operation | Unsupported transaction | Transaction type not supported/authorized for the account |
AM02 | Amount | Value exceeds limit | Value exceeds the limit allowed for the account type |
AM09 | Amount | Value mismatch | Refund amount exceeds the original payment order |
BE01 | Identification | Inconsistent CPF/CNPJ | CPF/CNPJ not consistent with account holder |
BE17 | Identification | QR Code rejected | QR Code rejected by the receiver’s participant |
CH11 | CPF/CNPJ | Incorrect CPF/CNPJ | Receiver’s CPF/CNPJ is incorrect or invalid |
DS04 | Processing | Order rejected by receiver | Rejected by the Receiver’s PSP for operational reasons |
DS24 | Processing | Authorization timeout | Timeout between PAIN.013 and PACS.008 (recurring authorization) |
DT05 | Date | Invalid or expired date | Invalid or expired cut-off date |
RR04 | Regulation | Regulatory reason | Rejection due to regulatory compliance or legal requirements |
SL02 | Settlement | Invalid account number | Invalid account for settlement |
These codes are defined by the Central Bank of Brazil and may be returned in
PIX operations involving communication with other banks.
Webhooks
| Code | HTTP | Description | Solution |
|---|
WEBHOOK_NOT_FOUND | 404 | Webhook doesn’t exist | Check configId |
INVALID_URL | 400 | Invalid URL | Use valid HTTPS |
DUPLICATE_WEBHOOK | 409 | Duplicate webhook | Use different URL |
Rate Limiting
| Code | HTTP | Description | Solution |
|---|
RATE_LIMIT_EXCEEDED | 429 | Too many requests | Wait and implement backoff |
Error Handling
JavaScript Example
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("Invalid credentials")
case 403:
throw new Error("IP not allowed")
case 429:
// Implement 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
}
}
Python Example
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
Best Practices
Log Request IDs
Always log the requestId to facilitate debugging with support.
Exponential Backoff
Implement retry with exponential backoff for 429 and 5xx errors.
Circuit Breaker
Use circuit breaker to avoid cascading failures.
Monitoring
Monitor error rate and latency per endpoint.