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 requestIdstring Unique UUID for tracking statusnumber HTTP code successboolean Always false on errors messagestring Human-readable error description hintstring Suggestion on how to resolve codestring 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 UNAUTHORIZED401 Invalid credentials Check API Key and Secret TOKEN_INVALID401 Invalid or expired token Generate a new token TOKEN_MISSING401 Token not provided Include token in header TOKEN_EXPIRED401 Token expired Generate a new token UNAUTHORIZED_ACCESS403 Unauthorized access Check user permissions API_KEY_NOT_FOUND404 API Key doesn’t exist Generate a new credential IP_NOT_ALLOWED403 IP not in allowlist Add your IP in the dashboard ACCESS_DENIED403 Access denied Check permissions
Validation Code HTTP Description Solution VALIDATION_ERROR400 Required field missing Check required fields FIELD_REQUIRED400 Required field Provide missing field INVALID_FIELD400 Invalid field format Check field format INVALID_AMOUNT400 Invalid value Use positive number INVALID_PIX_KEY400 Invalid PIX key Check key format INVALID_CPF_CNPJ400 Invalid CPF/CNPJ Use numbers only INVALID_DATE_RANGE400 Invalid date range Check start and end INVALID_REQUEST400 Invalid request Check parameters
Resources Code HTTP Description Solution RESOURCE_NOT_FOUND404 Resource not found Check the provided ID USER_NOT_FOUND404 User not found Check the userId USER_ALREADY_EXISTS409 User already exists Use another email/document USER_ALREADY_BLOCKED400 User already blocked User is already blocked USER_NOT_BLOCKED400 User is not blocked User is not blocked BANK_ACCOUNT_NOT_FOUND404 Bank account not found Check the accountId ACCOUNT_BLOCKED403 Account blocked Contact support WEBHOOK_CONFIG_NOT_FOUND404 Webhook config not found Check the configId FEE_TIER_NOT_FOUND404 Fee tier not found Configure fee tiers LIMIT_RULE_NOT_FOUND404 Limit rule not found Configure limit rules
PIX IN Code HTTP Description Solution QRCODE_EXPIRED400 QR Code expired Generate a new QR Code QRCODE_NOT_FOUND404 QR Code doesn’t exist Check the txId INVALID_QR_CODE400 Invalid QR Code Check QR Code format REFUND_NOT_ALLOWED400 Refund not allowed Check refund deadline ALREADY_REFUNDED400 Already refunded Transaction was refunded REFUND_FAILED400 Refund failed Try again or contact support INSUFFICIENT_BALANCE400 Insufficient balance Deposit more funds PIX_IN_PROCESSING400 PIX in processing Wait and try again TRANSACTION_NOT_FOUND404 Transaction not found Check the endToEndId ENTRY_NOT_FOUND404 Ledger entry not found Check the entry ID NOT_A_REFUND400 Transaction is not refund Use a refund transaction
DICT Query (PIX Keys) Errors returned when querying PIX keys in the DICT (Directory of Transactional Account Identifiers):
Code HTTP Description Solution DICT_KEY_NOT_FOUND404 PIX key not found in DICT Key doesn’t exist or is inactive. Verify and try again DICT_ENTRY_FRAUD_RESTRICTED400 Key linked to account with fraud suspicion Account or user restricted due to substantiated fraud suspicion DICT_ENTRY_USER_RESTRICTED400 Key linked to restricted user User associated with key has restrictions. Transaction not allowed DICT_ENTRY_ACCOUNT_RESTRICTED400 Key linked to restricted account Account associated with key has restrictions. Transaction not allowed DICT_ENTRY_OWNERSHIP_CONFLICT400 Key ownership conflict Key has an ownership conflict. Verify with the recipient DICT_QUERY_FORBIDDEN403 DICT query denied Operation denied by the Central Bank DICT_QUERY_RATE_LIMITED429 DICT query rate limit exceeded Too many queries in a short time. Wait a few minutes DICT_QUERY_ERROR502 Error querying key in DICT Error communicating with DICT. Try again DICT_SERVICE_TIMEOUT504 DICT query timeout DICT service is slow. Wait and try again
Fraud restriction errors (DICT_ENTRY_FRAUD_RESTRICTED) indicate that the queried PIX key is associated with an account or user with substantiated fraud suspicion at the Central Bank. Transactions with this key are not allowed. This is a protection mechanism of the SPI (Instant Payment System).
PIX OUT Code HTTP Description Solution TRANSFER_FAILED400 Transfer failed Check recipient data PIX_KEY_NOT_FOUND404 PIX key doesn’t exist Confirm key with recipient PIX_KEY_ALREADY_EXISTS409 PIX key already exists Use another key PIX_KEY_CREATION_BLOCKED400 Key creation blocked Account blocked for keys DAILY_LIMIT_EXCEEDED400 Daily limit exceeded Wait for next day BLOCKED_RECIPIENT403 Blocked recipient Contact support TRANSFER_WRONG_STATUS400 Invalid transfer status Check current status ENDTOEND_ALREADY_EXISTS409 EndToEndId already exists Use another endToEndId WITHDRAWAL_RESTRICTION_BLOCKED422 Account restricted for withdrawals by document Check account restriction settings
Limits and Time Restrictions Code HTTP Description Solution LIMIT_EXCEEDED_PER_TX422 Per-transaction limit exceeded Reduce the amount LIMIT_EXCEEDED_DAILY422 Daily limit exceeded Wait for next day LIMIT_EXCEEDED_MONTHLY422 Monthly limit exceeded Wait for next month LIMIT_EXCEEDED_PER_TX_NIGHT422 Night limit exceeded Reduce amount or wait until 8 AM (night window: 8 PM–8 AM) REQUEST_FORBIDDEN_TIME422 Forbidden time Wait for allowed hours (night window: 8 PM–8 AM)
MED (Special Return Mechanism) Code HTTP Description Solution MED_NOT_FOUND404 MED not found Check the MED ID MED_NOT_AWAITING_DEFENSE400 MED not awaiting defense MED already responded/expired MED_DEFENSE_FILE_REQUIRED400 Defense file required Upload defense file
BACEN/SPI Codes Errors returned by the Brazilian Central Bank’s Instant Payment System (SPI):
Code Category Meaning Description AB03Settlement SPI Timeout Settlement interrupted by timeout in the Instant Payment System AB09Settlement Receiver participant error Error at the receiver’s PSP (bank) when processing the request AC03Account Invalid account number Receiver’s branch and/or account does not exist or is invalid AC06Account Blocked account Specified account is blocked for transactions AC07Account Closed account Transactional account closed at the Receiver’s PSP AC14Account Invalid account type Incorrect type for the specified transactional account AG03Operation Unsupported transaction Transaction type not supported/authorized for the account AM02Amount Value exceeds limit Value exceeds the limit allowed for the account type AM09Amount Value mismatch Refund amount exceeds the original payment order BE01Identification Inconsistent CPF/CNPJ CPF/CNPJ not consistent with account holder BE17Identification QR Code rejected QR Code rejected by the receiver’s participant CH11CPF/CNPJ Incorrect CPF/CNPJ Receiver’s CPF/CNPJ is incorrect or invalid DS04Processing Order rejected by receiver Rejected by the Receiver’s PSP for operational reasons DS24Processing Authorization timeout Timeout between PAIN.013 and PACS.008 (recurring authorization) DT05Date Invalid or expired date Invalid or expired cut-off date RR04Regulation Regulatory reason Rejection due to regulatory compliance or legal requirements SL02Settlement 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_FOUND404 Webhook doesn’t exist Check configId INVALID_URL400 Invalid URL Use valid HTTPS DUPLICATE_WEBHOOK409 Duplicate webhook Use different URL
Rate Limiting Code HTTP Description Solution RATE_LIMIT_EXCEEDED429 Too many requests Wait and implement backoff
System Errors Code HTTP Description Solution INTERNAL_ERROR500 Internal server error Try again or contact support SERVICE_UNAVAILABLE503 Service unavailable Wait and try again TIMEOUT504 Request timeout Try again EXTERNAL_SERVICE_ERROR502 External service error Try again
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.
